Table of Contents

serial

`serial` opens a serial port, writes data, reads data, and can monitor incoming data asynchronously.

Read operations return `bytes` objects. Write operations accept a `bytes` object, string, or single byte number.

`serial` is not cloneable because it owns an operating-system serial port handle and optional monitor thread state.

Constructor

serial()

Creates a closed serial port object.

Item Description
Syntax `serial()`
Arguments none
Returns serial object

Example: 

port = serial();
print(port.is_open());       // false

Properties

`serial` has no object-specific properties.

Use methods such as `is_open()`, `is_monitoring()`, and `last_error()` to inspect serial state.

Common Object Methods

to_string()

Returns a display string for the object.

Item Description
Syntax `value.to_string()`
Arguments none
Returns string

Example: 

text = value.to_string();

`clone()` is not supported for `serial`.

Methods

open(port)

Opens a serial port using the default baud rate `115200`.

Argument Type Description
`port` string Serial port name, such as `COM1` on Windows or `/dev/ttyUSB0` on Linux.

Returns: boolean-style number.

If the port cannot be opened, returns `false` and stores the error text.

Example: 

port = serial();
ok = port.open('COM1');

open(port, baud)

Opens a serial port using the specified baud rate.

Argument Type Description
`port` string Serial port name.
`baud` number Baud rate. Values less than `1` are treated as `1`.

Returns: boolean-style number.

Example: 

port = serial();
ok = port.open('COM1', 9600);

close()

Stops monitoring if needed, then closes the serial port.

Item Description
Syntax `serial.close()`
Arguments none
Returns boolean-style number

Returns `true` when the port was closed or was already closed. If closing fails, returns `false` and stores the error text.

Example: 

port.close();

is_open()

Returns true when the serial port is open.

Item Description
Syntax `serial.is_open()`
Arguments none
Returns boolean-style number

Example: 

if (port.is_open())
{
    print('serial ready');
}

write(data)

Writes data to the serial port.

Argument Type Description
`data` bytes, string, or number A `bytes` object writes all bytes, a string writes its text bytes, and a number writes one byte.

Returns: number of bytes written. If writing fails, returns `none()` and stores the error text.

Example: 

port.write('G0 X0 Y0\n');
port.write(13);

read()

Reads up to 256 bytes from the serial port.

Item Description
Syntax `serial.read()`
Arguments none
Returns bytes object, or none

A timeout returns an empty `bytes` object. Other read errors return `none()` and store the error text.

Example: 

data = port.read();
print(data.size());

read(maxBytes)

Reads up to `maxBytes` bytes from the serial port.

Argument Type Description
`maxBytes` number Maximum number of bytes to read. `0` is treated as `1`.

Returns: bytes object, or none.

Example: 

data = port.read(64);

monitor(callback)

Starts asynchronous reading.

Argument Type Description
`callback` callable object Function reference, method reference, or other object that implements `call(data)`.

Returns: boolean-style number.

The callback receives one argument: a `bytes` object containing the received bytes.

Example: 

function OnSerialData(data)
{
    print('bytes: ', data.size());
}
 
port = serial();
if (port.open('COM1', 115200))
{
    port.monitor(OnSerialData);
}

stop_monitor()

Stops asynchronous monitoring.

Item Description
Syntax `serial.stop_monitor()`
Arguments none
Returns boolean-style number

Returns `true` if monitoring was active, otherwise returns `false`.

Example: 

port.stop_monitor();

is_monitoring()

Returns true while asynchronous monitoring is active.

Item Description
Syntax `serial.is_monitoring()`
Arguments none
Returns boolean-style number

Example: 

if (port.is_monitoring())
{
    print('serial monitor active');
}

last_error()

Returns the last serial error message.

Item Description
Syntax `serial.last_error()`
Arguments none
Returns string

Returns an empty string when no error is stored.

Example: 

if (!port.open('COM1'))
{
    print(port.last_error());
}

clear_error()

Clears the stored error message.

Item Description
Syntax `serial.clear_error()`
Arguments none
Returns boolean-style number

Example: 

port.clear_error();

help()

Returns a short text summary of serial methods.

Item Description
Syntax `serial.help()`
Arguments none
Returns string

Previous: Comm

Next: Dialogs