Prev: Module bt: Bluetooth Communication

Module comm: Serial Communications

This module provides access to the (usually software emulated) serial ports of the phone. Each communications device capable of performing serial communications is identified by its name ("module name" in Symbian OS). Serial communication is often emulated by a device capable of multiplexing, a device may offer multiple units.

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

Once created, a serial port is accessed via module io:

• 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

• function config(port) → Array
• function config(port, config) → Array
  Permissions: FreeComm

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

• function link(port, timeout=-1) → Boolean

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

• function open(name, unit, dceRole=false) → Native Object
  Permissions: FreeComm

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

• function signal(port) → Number
• function signal(port, signals, mask=0x3f) → Number
  Permissions: FreeComm

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

• function units(name) → Array
  Permissions: FreeComm

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]

---

Next: Module net: TCP/IP Networking

Navigation