Documentation/driver-api/serial/n_gsm.rst

   1 ==============================
   2 GSM 0710 tty multiplexor HOWTO
   3 ==============================
   4
   5 This line discipline implements the GSM 07.10 multiplexing protocol
   6 detailed in the following 3GPP document:
   7
   8         https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
   9
  10 This document give some hints on how to use this driver with GPRS and 3G
  11 modems connected to a physical serial port.
  12
  13 How to use it
  14 -------------
  15 1. config initiator
  16 ^^^^^^^^^^^^^^^^^^^^^
  17
  18 1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through
  19     its serial port. Depending on the modem used, you can pass more or less
  20     parameters to this command.
  21
  22 1.2 switch the serial line to using the n_gsm line discipline by using
  23     TIOCSETD ioctl.
  24
  25 1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
  26
  27 1.4 obtain base gsmtty number for the used serial port.
  28
  29 Major parts of the initialization program :
  30 (a good starting point is util-linux-ng/sys-utils/ldattach.c)::
  31
  32   #include <stdio.h>
  33   #include <stdint.h>
  34   #include <linux/gsmmux.h>
  35   #include <linux/tty.h>
  36   #define DEFAULT_SPEED B115200
  37   #define SERIAL_PORT   /dev/ttyS0
  38
  39         int ldisc = N_GSM0710;
  40         struct gsm_config c;
  41         struct termios configuration;
  42         uint32_t first;
  43
  44         /* open the serial port connected to the modem */
  45         fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
  46
  47         /* configure the serial port : speed, flow control ... */
  48
  49         /* send the AT commands to switch the modem to CMUX mode
  50            and check that it's successful (should return OK) */
  51         write(fd, "AT+CMUX=0\r", 10);
  52
  53         /* experience showed that some modems need some time before
  54            being able to answer to the first MUX packet so a delay
  55            may be needed here in some case */
  56         sleep(3);
  57
  58         /* use n_gsm line discipline */
  59         ioctl(fd, TIOCSETD, &ldisc);
  60
  61         /* get n_gsm configuration */
  62         ioctl(fd, GSMIOC_GETCONF, &c);
  63         /* we are initiator and need encoding 0 (basic) */
  64         c.initiator = 1;
  65         c.encapsulation = 0;
  66         /* our modem defaults to a maximum size of 127 bytes */
  67         c.mru = 127;
  68         c.mtu = 127;
  69         /* set the new configuration */
  70         ioctl(fd, GSMIOC_SETCONF, &c);
  71         /* get first gsmtty device node */
  72         ioctl(fd, GSMIOC_GETFIRST, &first);
  73         printf("first muxed line: /dev/gsmtty%i\n", first);
  74
  75         /* and wait for ever to keep the line discipline enabled */
  76         daemon(0,0);
  77         pause();
  78
  79 1.5 use these devices as plain serial ports.
  80
  81    for example, it's possible:
  82
  83    - and to use gnokii to send / receive SMS on ttygsm1
  84    - to use ppp to establish a datalink on ttygsm2
  85
  86 1.6 first close all virtual ports before closing the physical port.
  87
  88    Note that after closing the physical port the modem is still in multiplexing
  89    mode. This may prevent a successful re-opening of the port later. To avoid
  90    this situation either reset the modem if your hardware allows that or send
  91    a disconnect command frame manually before initializing the multiplexing mode
  92    for the second time. The byte sequence for the disconnect command frame is::
  93
  94       0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9.
  95
  96 2. config requester
  97 ^^^^^^^^^^^^^^^^^^^^^
  98
  99 2.1 receive string "AT+CMUX= command" through its serial port,initialize
 100     mux mode config
 101
 102 2.2 switch the serial line to using the n_gsm line discipline by using
 103     TIOCSETD ioctl.
 104
 105 2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
 106
 107 2.4 obtain base gsmtty number for the used serial port::
 108
 109   #include <stdio.h>
 110   #include <stdint.h>
 111   #include <linux/gsmmux.h>
 112   #include <linux/tty.h>
 113   #define DEFAULT_SPEED B115200
 114   #define SERIAL_PORT   /dev/ttyS0
 115
 116         int ldisc = N_GSM0710;
 117         struct gsm_config c;
 118         struct termios configuration;
 119         uint32_t first;
 120
 121         /* open the serial port */
 122         fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
 123
 124         /* configure the serial port : speed, flow control ... */
 125
 126         /* get serial data and check "AT+CMUX=command" parameter ... */
 127
 128         /* use n_gsm line discipline */
 129         ioctl(fd, TIOCSETD, &ldisc);
 130
 131         /* get n_gsm configuration */
 132         ioctl(fd, GSMIOC_GETCONF, &c);
 133         /* we are requester and need encoding 0 (basic) */
 134         c.initiator = 0;
 135         c.encapsulation = 0;
 136         /* our modem defaults to a maximum size of 127 bytes */
 137         c.mru = 127;
 138         c.mtu = 127;
 139         /* set the new configuration */
 140         ioctl(fd, GSMIOC_SETCONF, &c);
 141         /* get first gsmtty device node */
 142         ioctl(fd, GSMIOC_GETFIRST, &first);
 143         printf("first muxed line: /dev/gsmtty%i\n", first);
 144
 145         /* and wait for ever to keep the line discipline enabled */
 146         daemon(0,0);
 147         pause();
 148
 149 Additional Documentation
 150 ------------------------
 151 More practical details on the protocol and how it's supported by industrial
 152 modems can be found in the following documents :
 153
 154 - http://www.telit.com/module/infopool/download.php?id=616
 155 - http://www.u-blox.com/images/downloads/Product_Docs/LEON-G100-G200-MuxImplementation_ApplicationNote_%28GSM%20G1-CS-10002%29.pdf
 156 - http://www.sierrawireless.com/Support/Downloads/AirPrime/WMP_Series/~/media/Support_Downloads/AirPrime/Application_notes/CMUX_Feature_Application_Note-Rev004.ashx
 157 - http://wm.sim.com/sim/News/photo/2010721161442.pdf
 158
 159 11-03-08 - Eric Bénard - <eric@eukrea.com>