Module comm: Serial Communications

Often available devices are:

Device	Name	Unit
USB Serial Port	ecacm	1
Infrared (IrDA)	ircomm	0
Bluetooth Serial Port	btcomm	0

Note that not all devices are available on all phones, e.g. because the hardware or the appropriate driver are missing. Furthermore, the names and available units may also differ between phone models. Some units may already be used by the system software on the phone. A bit of try and error may be required to create a working connection.

Because of all these restrictions, use of serial communications should be avoided in m applications designed to be portable.

• Serial Ports Are Streams
• comm.config
• comm.link
• comm.open
• comm.signal
• comm.units

Serial Ports Are Streams

• io.read, io.readln, and io.readm receive data,
• io.write, io.writeln, io.writem, io.print, and io.println send data,
• io.avail gets the number of bytes which can be read without blocking,
• io.wait waits for data which can be read without blocking,
• io.close closes the connection.
• io.ces gets and sets the character encoding scheme. As with files, the default is io.raw.
• io.timeout sets the timeout for send and receive operations.
• io.flush sets the auto flush state. If auto flushing is disabled, io.flush must be called to make sure all data is sent.

comm.config

With one parameter, gets the configuration of the serial port port. port must have been obtained via comm.open.

With two parameters, sets the configuration from the fields in the array config, and returns the old configuration.

Configurations are represented by an array with the following elements:

Key	Meaning	Type
bps	Speed of the port (bits per second)	Number
data	Number of data bits (5 to 8)	Number
stop	Number of stop bits (1 to 2)	Number
parity	Parity bit (0 to 4 corresponding to none, even, odd, mark, space)	Number
terms	Characters considered terminators	String

// open an infrared port s=comm.open("ircomm", 0) // set it to 4 Mbit/s, 8 data and 1 stop bit, no parity print comm.config(s, ["bps":4000000, "data":8,                       "stop":1, "parity":0]) → [9600,8,1,0,]

comm.link

Attempts to establish a link open for reading and writing, waiting until the other end allows writing. Returns true as soon as the link is up.

If timeout>=0 and timeout milliseconds have passed without the link coming up, false is returned.

Throws ExcValueOutOfRange if timeout exceeds 2147483 (35 minutes and 47.483 seconds).

Reading from or writing to the port will also establish a link.

See comm.signal for an example.

comm.open

Opens a serial port for communication over the device with name name, using unit unit, and returns a stream object representing the port. unit must be in the range returned by comm.units. If dceRole=false, the serial port is working as a data terminal equipment; if dceRole=true, it is working as a data computer equipment.

Throws ErrNotFound if a device with this name does not exist. Throws ExcIndexOutOfRange if the unit is not within the range returned by comm.units.

The following example communicates with a PC over the USB cable. If you use a terminal application on the PC communicating over the corresponding port[15], the tiny program will echo every line typed into the terminal application, converted to uppercase.

// Open a port to communicate with a PC s=comm.open("ecacm", 1); while true do   l=io.readln(s);   io.writeln(s, upper(l)) end

comm.signal

With one parameter, gets the (input) signals of the serial port port. port must have been obtained via comm.open.

With two or three parameters, sets the (output) signals of the serial port contained in mask to the corresponding bit values in signals.

The signal bits are:

• const cts = 1 Clear to send signal (input).
• const dcd = 4 Data carrier detect signal (input).
• const dsr = 2 Data set ready signal (input).
• const dtr = 32 Data terminal ready signal (output).
• const rts = 16 Ready to send signal (output).

// open an infrared port s=comm.open("ircomm", 0) // wait until a connection appears print comm.link(s) → true // wait until the connection disappears again while comm.signal(s) & comm.dsr # 0 do   sleep(1000); print comm.signal() end → 3 ... 3 0

comm.units

Gets the range of units the device with name name supports. The range is returned as [minUnit,maxUnit].

Throws ErrNotFound if a device with this name does not exist.

// Get the units of the IrDA device print comm.units("ircomm") → [0,15]