Documentation/driver-api/tty/n_gsm.rst

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