serial#

class platypush.plugins.serial.SerialPlugin(*_, **__)[source]#

Bases: SensorPlugin

The serial plugin can read data from a serial device.

If the device returns a JSON string, then that string will be parsed for individual values. For example:

{"temperature": 25.0, "humidity": 15.0}

If the serial device returns such a value, then temperature and humidity will be parsed as separate entities with the same names as the keys provided on the payload.

The JSON option is a good choice if you have an Arduino/ESP-like device whose code you can control, as it allows to easily send data to Platypush in a simple key-value format. The use-case would be that of an Arduino/ESP device that pushes data on the wire, and this integration would then listen for updates.

Alternatively, you can also use this integration in a more traditional way through the read() and write() methods to read and write data to the device. In such a case, you may want to disable the “smart polling” by setting enable_polling to False in the configuration.

If you want an out-of-the-box solution with a Firmata-compatible firmware, you may consider using the platypush.plugin.arduino.ArduinoPlugin instead.

Note that device paths on Linux may be subject to change. If you want to create static naming associations for your devices (e.g. make sure that your Arduino will always be symlinked to /dev/arduino instead of /dev/ttyUSB<n>), you may consider creating static mappings through udev.

Requires:

  • pyserial (pip install pyserial)

Triggers:

__init__(device: str | None = None, baud_rate: int = 9600, max_size: int = 524288, timeout: float = 2.0, enable_polling: bool = True, poll_interval: float = 0.1, **kwargs)[source]#
Parameters:

  • device – Device path (e.g. /dev/ttyUSB0 or /dev/ttyACM0)

  • baud_rate – Serial baud rate (default: 9600)

  • max_size – Maximum size of a JSON payload (default: 512 KB). The plugin will keep reading bytes from the wire until it can form a valid JSON payload, so this upper limit is required to prevent the integration from listening forever and dumping garbage in memory.

  • timeout – This integration will ensure that only one reader/writer can access the serial device at the time, in order to prevent mixing up bytes in the response. This value specifies how long we should wait for a pending action to terminate when we try to run a new action. Default: 2 seconds.

  • enable_polling – If False, the plugin will not poll the device for updates. This can be the case if you want to programmatically interface with the device via the read() and write() methods instead of polling for updates in JSON format.

  • poll_interval – How often (in seconds) we should poll the device for new data. Since we are reading JSON data from a serial interface whenever it’s ready, the default here can be quite low (default: 0.1 seconds).

get_measurement(*_, device: str | None = None, baud_rate: int | None = None, **__) → Dict[str, int | float][source]#

Reads JSON data from the serial device and returns it as a message

Parameters:

  • device – Device path (default: default configured device).

  • baud_rate – Baud rate (default: default configured baud_rate).

main()[source]#

Implementation of the main loop of the plugin.

read(device: str | None = None, baud_rate: int | None = None, size: int | None = None, end: str | int | None = None, binary: bool = False) → str[source]#

Reads raw data from the serial device

Parameters:

  • device – Device to read (default: default configured device)

  • baud_rate – Baud rate (default: default configured baud_rate)

  • size – Number of bytes to read

  • end – End of message, as a character or bytecode

  • binary – If set to True, then the serial output will be interpreted as binary data and a base64-encoded representation will be returned. Otherwise, the output will be interpreted as a UTF-8 encoded string.

Returns:

The read message as a UTF-8 string if binary=False, otherwise as a base64-encoded string.

stop()[source]#

Stop the plugin.

transform_entities(entities: Dict[str, int | float]) → List[Device][source]#

This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

write(data: str | dict | list | bytes | bytearray, device: str | None = None, baud_rate: int | None = None, binary: bool = False)[source]#

Writes data to the serial device.

Parameters:

  • device – Device to write (default: default configured device).

  • baud_rate – Baud rate (default: default configured baud_rate).

  • data –

    Data to send to the serial device. It can be any of the following:

    • A UTF-8 string

    • A base64-encoded string (if binary=True)

    • A dictionary/list that will be encoded as JSON

    • A bytes/bytearray sequence

  • binary – If True, then the message is either a bytes/bytearray sequence or a base64-encoded string.