Serial

pybarst.serial

Serial channel

The Barst serial port interface. A serial channel is an interface to a serial port, such as a RS232 or RS485 port. See SerialChannel for details.

Typical usage

For the serial channel, once a channel is created on the server, it’s always active. That means that there’s no need to set the state with set_state().

Typically, a client creates a SerialChannel and then calls SerialChannel.open_channel() on it to create the channel on the server. Once created, the client can read and write to it through the server using SerialChannel.read() and SerialChannel.write().

Other clients can do similarly; they create a new SerialChannel instance and then call SerialChannel.open_channel() on it to open a new connection to the existing channel. Those new clients can then read/write to the channel as well.

Finally, existing clients can call close_channel_client() to simply close this client while leaving the channel on the server, or close_channel_server() to delete the channel from the server as well as for all the clients.

class pybarst.serial.SerialChannel(BarstServer server, port_name, max_write, max_read, baud_rate=9600, stop_bits=1, parity='none', byte_size=8, **kwargs)

Bases: pybarst.core.server.BarstChannel

A serial port interface channel.

A serial port channel controls a single serial port.

Parameters:

server: BarstServer

An instance of a server through which this channel is opened.

port_name: str

The name of the port this channel controls. See port_name.

max_write: unsigned int

The maximum number of bytes written to the port. See max_write.

max_read: unsigned int

The maximum number of bytes read from the port. See max_read.

baud_rate: unsigned int

The baud rate to use for the port. See baud_rate. Defaults to 9600.

stop_bits: float

The number of stop bits to use. See stop_bits. Defaults to 1.

parity: str

The parity scheme to use. See parity. Defaults to ‘none’.

byte_size: unsigned char

The number of bits in the bytes transmitted and received. See byte_size. Defaults to 8.

In the following example, a loopback cable was connected to the com3 serial port:

>>> # open the com3 port and read/write a maximum of 32 chars.
>>> serial = SerialChannel(server=server, port_name='COM3', max_write=32, max_read=32)
>>> serial.open_channel()
>>> print serial
<pybarst.serial._serial.SerialChannel object at 0x024C06F0>
>>> print serial.write(value='cheesecake and fries.', timeout=10000)
(0.0525455800455579, 21)
>>> print serial.read(read_len=21, timeout=10000)
(0.056576697876712934, 'cheesecake and fries.')
>>> print serial.write(value='apples.', timeout=10000)
(0.06754473171193724, 7)
>>> print serial.read(read_len=7, timeout=10000)
(0.07514634606696861, 'apples.')

baud_rate

baud_rate: ‘DWORD’

The baud rate to use for the serial port when opening it.

byte_size

byte_size: ‘unsigned char’

The number of bits in the bytes transmitted and received. Can be between 4 and 8, including 4 and 8.

max_read

max_read: ‘DWORD’

The maximum number of bytes that will be read from the serial port at any time. I.e. the maximum value of the read_len parameter in write().

max_write

max_write: ‘DWORD’

The maximum number of bytes that will be written to the serial port at any time. I.e. the maximum length of the value parameter in read().

open_channel(self)

Opens the, possibly existing, channel on the server and connects the client to it. If the channel already exists, a new client connection will be opened to the channel.

See open_channel() for more details.

Note

If the channel already exists on the server, the settings used to initialize this client, e.g. parity will be overwritten by their values received from the existing server channel.

parity

parity: object

The parity scheme to use. Can be one of ‘even’, ‘odd’, ‘mark’, ‘none’, ‘space’.

port_name

port_name: object

The name of the port this channel controls. E.g. COM1, COM5 etc.

read(self, DWORD read_len, timeout=0, stop_char='')

Requests the server to read from the serial port and send the data back to this client. When multiple clients are connected simultaneously, and each requests a read, their read requests are performed in the order on which they were received.

The read request is initiated when this method is called and it waits until the server sends data back, returns an error, or times out. To terminate the waiting client, from another thread you must call close_channel_client(), or just close the channel or server, which will cause this method to return with an error.

Before this method can be called, open_channel() must be called`.

Parameters:

read_len: int

The number of bytes to read from the port. The value cannot exceed max_read.

timeout: unsigned int

The amount of time, in ms, the server should wait to finish the read request before returning. If zero, it won’t time out. Defaults to 0. After the timeout, if read_len chars was not read, the method just returns the data read and does not raise and exception.

stop_char: single character string

The character on which to finish the read, even if it’s less than read_len. When the server reads this character the read is completed and whatever read is returned. If stop_char is the empty string, ‘’, then the server doesn’t send data back until read_len bytes have been read, or it timed out. Defaults to the empty string, ‘’.

Returns:

2-tuple of (time, data). time is the time that the data was finished reading in channel time, clock(). data is a bytes instance containing the data read.

For example, with a loopback cable connected to com3:

>>> print serial.write(value='cheesecake and fries.', timeout=10000)
(0.0524498444040303, 21)
>>> # here we read the exact number of chars written.
>>> print serial.read(read_len=21, timeout=10000)
(0.05645847628379451, 'cheesecake and fries.')

>>> print serial.write(value='apples with oranges.', timeout=10000)
(0.08144922638106329, 20)
>>> # we read more than the number of chars written, forcing us to time out
>>> print serial.read(read_len=32, timeout=10000)
(10.087937104749782, 'apples with oranges.')

>>> print serial.write(value='apples with oranges.', timeout=10000)
(10.114267472435971, 20)
>>> # we read less than the number of chars written only returning those chars
>>> print serial.read(read_len=7, timeout=10000)
(10.116678238982054, 'apples ')
>>> # now we read the rest
>>> print serial.read(read_len=13, timeout=10000)
(10.118474730219688, 'with oranges.')

>>> print serial.write(value='apples with oranges.', timeout=10000)
(10.144263390895098, 20)
>>> # we read less than the number of chars written only returning those chars
>>> print serial.read(read_len=7, timeout=10000)
(10.146677223707279, 'apples ')
>>> # now write even more
>>> print serial.write(value='apples.', timeout=10000)
(10.159265949523808, 7)
>>> # in this read, everything we haven't read is returned
>>> print serial.read(read_len=32, timeout=10000)
(20.167324778223787, 'with oranges.apples.')

>>> print serial.write(value='apples with oranges.', timeout=10000)
(20.193081413453278, 20)
>>> # we read more than the number of chars written, but becuase of the stop
>>> # char, it doesn't wait to timeout, but returns everything it read when it
>>> # hit the stop char, which here was a few more chars of the text written
>>> print serial.read(read_len=32, timeout=10000, stop_char='o')
(20.19520872073334, 'apples with oran')
>>> # now finish up the read
>>> print serial.read(read_len=32, timeout=10000)
(30.198723343074974, 'ges.')

Note

When the method returns it might return up to a read_len character bytes string. Even if it times out or we hit the stop_char in the middle of the string, when specified, if the server already read less than or read_len characters, it returns them all.

set_state(self, int state, flush=False)

See set_state() for details.

Note

For the serial channel, this method doesn’t do anything, since after creation, the state of the channel on the server is always active.

stop_bits

stop_bits: ‘float’

The number of stop bits to use. Can be one of 1, 1.5, or 2.

write(self, value, timeout=0)

Requests the server to write value to the serial port.

The write request is initiated when this method is called and it waits until it finishes writing, it times out, or it returns an error. To terminate the waiting client, from another thread you must call close_channel_client(), or just close the channel or server, which will cause this method to return with an error.

Before this method can be called, open_channel() must be called.

Parameters:

value: str

The byte string to write to the port. The length of the bytes instance cannot exceed max_write.

timeout: unsigned int

The amount of time, in ms, the server should wait to finish the write request before returning with a timeout error. If zero, it won’t time out. Defaults to 0.

Returns:

2-tuple of (time, length). time is the time that the data was finished writing in channel time, clock(). length is the number of bytes actually written.

For example:

>>> print serial.write(value='cheesecake and fries.', timeout=10000)
(0.0525455800455579, 21)
>>> print serial.write(value='apples.', timeout=10000)
(0.06754473171193724, 7)