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
andhumidity
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()
andwrite()
methods to read and write data to the device. In such a case, you may want to disable the “smart polling” by settingenable_polling
toFalse
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 theread()
andwrite()
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).
- 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.
- 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.