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