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``/``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
100Config 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
15311-03-08 - Eric Bénard - <eric@eukrea.com>
154