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