n_gsm.rst

  1==============================
  2GSM 0710 tty multiplexor HOWTO
  3==============================
  4
  5.. contents:: :local:
  6
  7This line discipline implements the GSM 07.10 multiplexing protocol
  8detailed in the following 3GPP document:
  9
 10	https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
 11
 12This document give some hints on how to use this driver with GPRS and 3G
 13modems connected to a physical serial port.
 14
 15How to use it
 16=============
 17
 18Config 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
119Config 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
19211-03-08 - Eric Bénard - <eric@eukrea.com>