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_EXT``/``GSMIOC_SETCONF_EXT`` ioctl if needed.
  29
  30 #. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl.
  31
  32 #. Configure DLCs using ``GSMIOC_GETCONF_DLCI``/``GSMIOC_SETCONF_DLCI`` ioctl for non-defaults.
  33
  34 #. Obtain base gsmtty number for the used serial port.
  35
  36    Major parts of the initialization program
  37    (a good starting point is util-linux-ng/sys-utils/ldattach.c)::
  38
  39       #include <stdio.h>
  40       #include <stdint.h>
  41       #include <linux/gsmmux.h>
  42       #include <linux/tty.h>
  43
  44       #define DEFAULT_SPEED     B115200
  45       #define SERIAL_PORT       /dev/ttyS0
  46
  47       int ldisc = N_GSM0710;
  48       struct gsm_config c;
  49       struct gsm_config_ext ce;
  50       struct gsm_dlci_config dc;
  51       struct termios configuration;
  52       uint32_t first;
  53
  54       /* open the serial port connected to the modem */
  55       fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
  56
  57       /* configure the serial port : speed, flow control ... */
  58
  59       /* send the AT commands to switch the modem to CMUX mode
  60          and check that it's successful (should return OK) */
  61       write(fd, "AT+CMUX=0\r", 10);
  62
  63       /* experience showed that some modems need some time before
  64          being able to answer to the first MUX packet so a delay
  65          may be needed here in some case */
  66       sleep(3);
  67
  68       /* use n_gsm line discipline */
  69       ioctl(fd, TIOCSETD, &ldisc);
  70
  71       /* get n_gsm extended configuration */
  72       ioctl(fd, GSMIOC_GETCONF_EXT, &ce);
  73       /* use keep-alive once every 5s for modem connection supervision */
  74       ce.keep_alive = 500;
  75       /* set the new extended configuration */
  76       ioctl(fd, GSMIOC_SETCONF_EXT, &ce);
  77       /* get n_gsm configuration */
  78       ioctl(fd, GSMIOC_GETCONF, &c);
  79       /* we are initiator and need encoding 0 (basic) */
  80       c.initiator = 1;
  81       c.encapsulation = 0;
  82       /* our modem defaults to a maximum size of 127 bytes */
  83       c.mru = 127;
  84       c.mtu = 127;
  85       /* set the new configuration */
  86       ioctl(fd, GSMIOC_SETCONF, &c);
  87       /* get DLC 1 configuration */
  88       dc.channel = 1;
  89       ioctl(fd, GSMIOC_GETCONF_DLCI, &dc);
  90       /* the first user channel gets a higher priority */
  91       dc.priority = 1;
  92       /* set the new DLC 1 specific configuration */
  93       ioctl(fd, GSMIOC_SETCONF_DLCI, &dc);
  94       /* get first gsmtty device node */
  95       ioctl(fd, GSMIOC_GETFIRST, &first);
  96       printf("first muxed line: /dev/gsmtty%i\n", first);
  97
  98       /* and wait for ever to keep the line discipline enabled */
  99       daemon(0,0);
 100       pause();
 101
 102 #. Use these devices as plain serial ports.
 103
 104    For example, it's possible:
 105
 106    - to use *gnokii* to send / receive SMS on ``ttygsm1``
 107    - to use *ppp* to establish a datalink on ``ttygsm2``
 108
 109 #. First close all virtual ports before closing the physical port.
 110
 111    Note that after closing the physical port the modem is still in multiplexing
 112    mode. This may prevent a successful re-opening of the port later. To avoid
 113    this situation either reset the modem if your hardware allows that or send
 114    a disconnect command frame manually before initializing the multiplexing mode
 115    for the second time. The byte sequence for the disconnect command frame is::
 116
 117       0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9
 118
 119 Config Requester
 120 ----------------
 121
 122 #. Receive ``AT+CMUX=`` command through its serial port, initialize mux mode
 123    config.
 124
 125 #. Switch the serial line to using the *n_gsm* line discipline by using
 126    ``TIOCSETD`` ioctl.
 127
 128 #. Configure the mux using ``GSMIOC_GETCONF_EXT``/``GSMIOC_SETCONF_EXT``
 129    ioctl if needed.
 130
 131 #. Configure the mux using ``GSMIOC_GETCONF``/``GSMIOC_SETCONF`` ioctl.
 132
 133 #. Configure DLCs using ``GSMIOC_GETCONF_DLCI``/``GSMIOC_SETCONF_DLCI`` ioctl for non-defaults.
 134
 135 #. Obtain base gsmtty number for the used serial port::
 136
 137         #include <stdio.h>
 138         #include <stdint.h>
 139         #include <linux/gsmmux.h>
 140         #include <linux/tty.h>
 141         #define DEFAULT_SPEED   B115200
 142         #define SERIAL_PORT     /dev/ttyS0
 143
 144         int ldisc = N_GSM0710;
 145         struct gsm_config c;
 146         struct gsm_config_ext ce;
 147         struct gsm_dlci_config dc;
 148         struct termios configuration;
 149         uint32_t first;
 150
 151         /* open the serial port */
 152         fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY);
 153
 154         /* configure the serial port : speed, flow control ... */
 155
 156         /* get serial data and check "AT+CMUX=command" parameter ... */
 157
 158         /* use n_gsm line discipline */
 159         ioctl(fd, TIOCSETD, &ldisc);
 160
 161         /* get n_gsm extended configuration */
 162         ioctl(fd, GSMIOC_GETCONF_EXT, &ce);
 163         /* use keep-alive once every 5s for peer connection supervision */
 164         ce.keep_alive = 500;
 165         /* set the new extended configuration */
 166         ioctl(fd, GSMIOC_SETCONF_EXT, &ce);
 167         /* get n_gsm configuration */
 168         ioctl(fd, GSMIOC_GETCONF, &c);
 169         /* we are requester and need encoding 0 (basic) */
 170         c.initiator = 0;
 171         c.encapsulation = 0;
 172         /* our modem defaults to a maximum size of 127 bytes */
 173         c.mru = 127;
 174         c.mtu = 127;
 175         /* set the new configuration */
 176         ioctl(fd, GSMIOC_SETCONF, &c);
 177         /* get DLC 1 configuration */
 178         dc.channel = 1;
 179         ioctl(fd, GSMIOC_GETCONF_DLCI, &dc);
 180         /* the first user channel gets a higher priority */
 181         dc.priority = 1;
 182         /* set the new DLC 1 specific configuration */
 183         ioctl(fd, GSMIOC_SETCONF_DLCI, &dc);
 184         /* get first gsmtty device node */
 185         ioctl(fd, GSMIOC_GETFIRST, &first);
 186         printf("first muxed line: /dev/gsmtty%i\n", first);
 187
 188         /* and wait for ever to keep the line discipline enabled */
 189         daemon(0,0);
 190         pause();
 191
 192 11-03-08 - Eric Bénard - <eric@eukrea.com>