API Reference
Readers
SDS011 Reader module.
Contains multiple implementations of readers, for different use cases.
- SDS011QueryReader - (Recommended) A reader which operates exclusively in query mode.
- SDS011ActiveReader - A reader which operates exclusively in active mode
- SS011Reader - A lower-level reader, which isn't opinionated about the mode.
Attributes:
| Name | Type | Description |
|---|---|---|
ALL_SENSORS |
bytes
|
A special device ID which targets all sensors attached to a serial port. |
SDS011ActiveReader
Active Mode Reader.
Note that because active mode readers will constantly return data, this implementation opens and closes the serial port for each command.
__init__(ser_dev: Union[str, SerialLike], send_command_sleep: int = 2)
Create a reader which operates exclusively in active mode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ser_dev |
Union[str, SerialLike]
|
A path to a serial device, or an instance of serial.Serial. |
required |
send_command_sleep |
int
|
The number of seconds to sleep after sending a command to the device. |
2
|
query() -> QueryResponse
Query the device for pollutant data.
Returns:
| Type | Description |
|---|---|
QueryResponse
|
The latest pollutant data. |
set_device_id(device_id: bytes, target_device_id: bytes = ALL_SENSORS) -> DeviceIdResponse
Set the device ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The new, 4-byte device ID to set. |
required |
target_device_id |
bytes
|
The target device ID. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
DeviceIdResponse
|
A response with the new device ID. |
set_working_period(working_period: int, device_id: bytes = ALL_SENSORS) -> WorkingPeriodReadResponse
Set the working period for the device.
Working period must be between 0 and 30.
0 means the device will read continuously. Any value 1-30 means the device will wake and read for 30 seconds every n*60-30 seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
working_period |
int
|
A value 0-30 to set as the new working period |
required |
device_id |
bytes
|
The device ID to set the working period for. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
WorkingPeriodReadResponse
|
A response with the new working period |
sleep(device_id: bytes = ALL_SENSORS) -> SleepWakeReadResponse
Put the device to sleep, turning off fan and diode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to put to sleep. |
ALL_SENSORS
|
wake(device_id: bytes = ALL_SENSORS) -> SleepWakeReadResponse
Wake the device up to start reading, turning on the fan and diode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to wake up. |
ALL_SENSORS
|
SDS011QueryReader
Reader working in query mode.
__init__(ser_dev: Union[str, SerialLike], send_command_sleep: int = 1)
Create a reader which operates exclusively in query mode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ser_dev |
Union[str, SerialLike]
|
A path to a serial device, or an instance of serial.Serial. |
required |
send_command_sleep |
int
|
The number of seconds to sleep after sending a command to the device. |
1
|
get_firmware_version(device_id: bytes = ALL_SENSORS) -> CheckFirmwareResponse
Retrieve the firmware version from the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to retrieve firmware version for. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
CheckFirmwareResponse
|
The firmware version of the device |
get_reporting_mode(device_id: bytes = ALL_SENSORS) -> ReportingModeResponse
Get the current reporting mode of the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to get the reporting mode for. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
ReportingModeResponse
|
The current reporting mode of the device. |
get_sleep_state(device_id: bytes = ALL_SENSORS) -> SleepWakeReadResponse
Get the current sleep state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to get the sleep state for. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
SleepWakeReadResponse
|
The current sleep state of the device. |
get_working_period(device_id: bytes = ALL_SENSORS) -> WorkingPeriodReadResponse
Retrieve the current working period for the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to get the working period for. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
WorkingPeriodReadResponse
|
A response with the current working period. |
query(device_id: bytes = ALL_SENSORS) -> QueryResponse
Query the device for pollutant data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to get pollutant data for. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
QueryResponse
|
The latest pollutant data. |
set_device_id(device_id: bytes, target_device_id: bytes = ALL_SENSORS) -> DeviceIdResponse
Set the device ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The new, 4-byte device ID to set. |
required |
target_device_id |
bytes
|
The target device ID. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
DeviceIdResponse
|
A response with the new device ID. |
set_working_period(working_period: int, device_id: bytes = ALL_SENSORS) -> WorkingPeriodReadResponse
Set the working period for the device.
Working period must be between 0 and 30.
0 means the device will read continuously. Any value 1-30 means the device will wake and read for 30 seconds every n*60-30 seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
working_period |
int
|
A value 0-30 to set as the new working period |
required |
device_id |
bytes
|
The device ID to set the working period for. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
WorkingPeriodReadResponse
|
A response with the new working period |
sleep(device_id: bytes = ALL_SENSORS) -> SleepWakeReadResponse
Put the device to sleep, turning off fan and diode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to put to sleep. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
SleepWakeReadResponse
|
The new sleep state of the device. |
wake(device_id: bytes = ALL_SENSORS) -> SleepWakeReadResponse
Wake the device up to start reading, turning on the fan and diode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The device ID to wake up. |
ALL_SENSORS
|
Returns:
| Type | Description |
|---|---|
SleepWakeReadResponse
|
The new sleep state of the device. |
SDS011Reader
NOVA PM SDS011 Reader.
__init__(ser_dev: Union[str, SerialLike], send_command_sleep: int = 1, max_loop_count: int = 30)
Create a basic device.
This is mostly a low level implementation. For practical purposes, most users will want to use the SDS011QueryReader or SDS011ActiveReader. This implementation would only be useful for very special cases, and serves as the base class for the other reader implementations anyways.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ser_dev |
Union[str, SerialLike]
|
A path to a serial device, or an instance of serial.Serial. |
required |
send_command_sleep |
int
|
The number of seconds to sleep after sending a command to the device. |
1
|
max_loop_count |
int
|
The maximum number of reads to search through to find a desired response command. |
30
|
query_data() -> QueryResponse
Query the device for pollutant data.
Returns:
| Type | Description |
|---|---|
QueryResponse
|
Pollutant data from the device. |
query_device_id() -> DeviceIdResponse
query_firmware_version() -> CheckFirmwareResponse
Retrieve the firmware version from the device.
Returns:
| Type | Description |
|---|---|
CheckFirmwareResponse
|
The firmware version from the device. |
query_reporting_mode() -> ReportingModeResponse
Get the current reporting mode of the device.
Returns:
| Type | Description |
|---|---|
ReportingModeResponse
|
The current reporting mode of the device. |
query_sleep_state() -> SleepWakeReadResponse
Get the current sleep state.
Returns:
| Type | Description |
|---|---|
SleepWakeReadResponse
|
The current sleep state of the device. |
query_working_period() -> WorkingPeriodReadResponse
Retrieve the current working period for the device.
Returns:
| Type | Description |
|---|---|
WorkingPeriodReadResponse
|
The current working period set for the device. |
request_data(device_id: bytes = ALL_SENSORS) -> None
Submit a request to the device to return pollutant data.
request_firmware_version(device_id: bytes = ALL_SENSORS) -> None
Submit a request to retrieve the firmware version from the device.
request_reporting_mode(device_id: bytes = ALL_SENSORS) -> None
Submit a request to the device to return the current reporting mode.
request_sleep_state(device_id: bytes = ALL_SENSORS) -> None
Submit a request to get the current sleep state.
request_working_period(device_id: bytes = ALL_SENSORS) -> None
Submit a request to retrieve the current working period for the device.
safe_wake(device_id: bytes = ALL_SENSORS) -> None
Wake the device up, if you don't know what mode its in.
This operates as a fire-and-forget, even in query mode. You shouldn't have to (and can't) query for a response after this command.
set_active_mode() -> None
Set the reporting mode to active.
set_device_id(device_id: bytes, target_device_id: bytes = ALL_SENSORS) -> None
Set the device ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_id |
bytes
|
The new device ID to set. |
required |
target_device_id |
bytes
|
The target device ID to set the new device ID on. |
ALL_SENSORS
|
set_query_mode() -> None
Set the reporting mode to querying.
set_sleep_state(sleep_state: SleepState, device_id: bytes = ALL_SENSORS) -> None
Set the sleep state, either wake or sleep.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sleep_state |
SleepState
|
The sleep state to set, either SleepState.WAKE or SleepState.SLEEP |
required |
device_id |
bytes
|
The device ID to sleep or wake. |
ALL_SENSORS
|
set_working_period(working_period: int, device_id: bytes = ALL_SENSORS) -> None
Set the working period for the device.
Working period must be between 0 and 30.
0 means the device will read continuously. Any value 1-30 means the device will wake and read for 30 seconds every n*60-30 seconds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
working_period |
int
|
A value 0-30 to set as the new working period |
required |
device_id |
bytes
|
The device ID to set the working period for. |
ALL_SENSORS
|
sleep(device_id: bytes = ALL_SENSORS) -> None
Put the device to sleep, turning off fan and diode.
wake(device_id: bytes = ALL_SENSORS) -> None
Wake the device up to start reading, turning on fan and diode.
SerialLike
Bases: Protocol
A serial-like device.
close() -> None
Close a connection to the device.
open() -> None
Open a connection to the device.
read(size: int) -> bytes
Read data from the device.
write(data: bytes) -> Optional[int]
Write data from the device.
Responses
sds011lib.responses
Response objects for SDS011.
Creates and validates typed classes from binary responses from the device.
CheckFirmwareResponse
dataclass
Response containing the firmware version.
Attributes:
| Name | Type | Description |
|---|---|---|
year |
int
|
The two-digit year of the firmware release. |
month |
int
|
The month of the firmware release. |
day |
int
|
The day of the firmware release. |
DeviceIdResponse
dataclass
Device ID response.
Attributes:
| Name | Type | Description |
|---|---|---|
device_id |
bytes
|
The 4 byte device ID. |
QueryResponse
dataclass
A query read response.
Attributes:
| Name | Type | Description |
|---|---|---|
pm25 |
float
|
The PM2.5 reading from the device |
pm10 |
float
|
The PM10 reading from the device. |
ReportingModeResponse
dataclass
Reporting mode response.
Attributes:
| Name | Type | Description |
|---|---|---|
operation_type |
OperationType
|
The operation type the response is for, either QUERY or SET_MODE. |
state |
ReportingMode
|
The current reporting mode, either ACTIVE or QUERYING |
SleepWakeReadResponse
dataclass
Sleep/Wake Response.
Attributes:
| Name | Type | Description |
|---|---|---|
operation_type |
OperationType
|
The operation type the response is for, either QUERY or SET_MODE. |
state |
SleepState
|
The current sleep state, either WAKE or SLEEP. |
WorkingPeriodReadResponse
dataclass
Working period response.
Attributes:
| Name | Type | Description |
|---|---|---|
operation_type |
OperationType
|
The operation type the response is for, either QUERY or SET_MODE. |
interval |
int
|
The working period interval, 0-30. 0 Indicates continuous reading. |
Exceptions
sds011lib.exceptions
All exception classes for the SDS011.
ChecksumFailedException
Bases: Sds011Exception
Thrown if the checksum value in a response is incorrect.
This indicates some corruption of the response.
Attributes:
| Name | Type | Description |
|---|---|---|
expected |
int
|
The expected checksum |
actual |
int
|
The actual checksum |
IncompleteReadException
Bases: Sds011Exception
Thrown if the device didn't return complete data when asking for a response.
Responses must be 10 bytes total. If the device doesn't respond with a complete 10 bytes, it can mean that either 1) The device is in sleep mode or 2) The device is in query mode, and nothing was requested.
IncorrectCommandCodeException
Bases: Sds011Exception
Thrown if the command code in a response is incorrect.
Attributes:
| Name | Type | Description |
|---|---|---|
expected |
bytes
|
The expected command code as bytes |
actual |
bytes
|
The actual command code as bytes. |
IncorrectCommandException
Bases: Sds011Exception
Thrown if the command ID in a response is incorrect.
Attributes:
| Name | Type | Description |
|---|---|---|
expected |
bytes
|
The expected command id as bytes |
actual |
bytes
|
The actual command id as bytes. |
IncorrectWrapperException
Bases: Sds011Exception
Thrown if the wrapper of a response (either HEAD or TAIL) is incorrect.
This indicates some corruption of the response.
InvalidDeviceIdException
Bases: Sds011Exception
Thrown if the trying to set the device ID on an invalid device.
This occurs if you try and send to a device ID that doesn't exist.
MissingResponseException
Bases: Sds011Exception
Thrown if we are trying to find a response from the device, but it doesn't return in the max iterations.
This can occur if the device just never responds to a command thats sent.
Sds011Exception
Bases: Exception
Base exception for SDS011 device.