1==============================
2GSM 0710 tty multiplexor HOWTO
3==============================
4
5This line discipline implements the GSM 07.10 multiplexing protocol
6detailed in the following 3GPP document:
7
8	https://www.3gpp.org/ftp/Specs/archive/07_series/07.10/0710-720.zip
9
10This document give some hints on how to use this driver with GPRS and 3G
11modems connected to a physical serial port.
12
13How to use it
14-------------
151. config initiator
16^^^^^^^^^^^^^^^^^^^^^
17
181.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.
211.2 switch the serial line to using the n_gsm line discipline by using
22    TIOCSETD ioctl.
231.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
241.4 obtain base gsmtty number for the used serial port.
25
26Major 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
761.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
831.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
932. config requester
94^^^^^^^^^^^^^^^^^^^^^
95
962.1 receive string "AT+CMUX= command" through its serial port,initialize
97    mux mode config
982.2 switch the serial line to using the n_gsm line discipline by using
99    TIOCSETD ioctl.
1002.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl.
1012.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
143Additional Documentation
144------------------------
145More practical details on the protocol and how it's supported by industrial
146modems 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
15311-03-08 - Eric Bénard - <eric@eukrea.com>
154