API Reference¶
Sfa3xShdlcDevice¶
-
class
sensirion_shdlc_sfa3x.device.
Sfa3xShdlcDevice
(connection, slave_address)[source]¶ SFA3x device.
This is a low-level driver which just provides all SHDLC commands as Python methods. Typically, calling a method sends one SHDLC request to the device and interprets its response. There is no higher level functionality available, please look for other drivers if you need a higher level interface.
There is no (or very few) caching functionality in this driver. For example if you call
get_device_marking()
100 times, it will send the command 100 times over the SHDLC interface to the device. This makes the driver (nearly) stateless.-
__init__
(connection, slave_address)[source]¶ Create a SFA3x device instance on an SHDLC connection.
Note
This constructor does not communicate with the device, so it’s possible to instantiate an object even if the device is not connected or powered yet.
Parameters: - connection (ShdlcConnection) – The connection used for the communication.
- slave_address (byte) – The address of the device. The default address of the SFA3x is 0.
-
get_device_marking
()[source]¶ Gets the device marking from the device.
Returns: The device marking as an ASCII string. Return type: string
-
start_measurement
()[source]¶ Starts continuous measurement in polling mode.
Note
This command is only available in idle mode.
-
stop_measurement
()[source]¶ Leaves the measurement mode and returns to the idle mode.
Note
This command is only available in measurement mode.
-
read_measured_values
()[source]¶ Returns the new measurement results.
Returns: The measured formaldehyde concentration, humidity and temperature. - hcho (
FormaldehydeConcentration
) - Formaldehyde concentration response object. - humidity (
Humidity
) - Humidity response object. - temperature (
Temperature
) - Temperature response object.
Return type: tuple Raises: Sfa3xNoMeasurementDataAvailable – If the measure mode was not started, or it was started but no measurement results are available yet. After starting the measurement, you have to wait at least 1 Second before reading any results. - hcho (
-
connection
¶ Get the used SHDLC connection.
Returns: The used SHDLC connection. Return type: ShdlcConnection
-
execute
(command)¶ Execute an SHDLC command.
Parameters: command (ShdlcCommand) – The command to execute. Returns: The interpreted response of the executed command.
-
last_error_flag
¶ Get the error flag which was received with the last response of the device. So this flag gets updated with every command sent to the device. If the flag is True, typically the derived classes provide a method to read the exact error reason from the device (the corresponding SHDLC command is called “Get Device Status”).
Note
When creating an instance of
ShdlcDeviceBase
, this property is initialized withFalse
and will not be updated until you send the first command to the device.Returns: True if the device indicated an error, False otherwise. Return type: bool
-
slave_address
¶ Get the slave address (not read from the device!).
Returns: The slave address. Return type: byte
-
Response Data Types¶
Formaldehyde Concentration¶
-
class
sensirion_shdlc_sfa3x.response_types.
FormaldehydeConcentration
(ticks)[source]¶ Represents a measurement response for the formaldehyde concentration.
With the
ticks
you can access the raw data as received from the device. For the converted value theppb
attribute is available.-
__init__
(ticks)[source]¶ Creates an instance from the received raw data.
Parameters: ticks (int) – The read ticks as received from the device.
-
ticks
¶ The ticks (int) as received from the device.
-
ppb
¶ The converted formaldehyde concentration.
-
Humidity¶
-
class
sensirion_shdlc_sfa3x.response_types.
Humidity
(ticks)[source]¶ Represents a measurement response for the humidity.
With the
ticks
you can access the raw data as received from the device. For the converted value thepercent_rh
attribute is available.-
__init__
(ticks)[source]¶ Creates an instance from the received raw data.
Parameters: ticks (int) – The read ticks as received from the device.
-
ticks
¶ The ticks (int) as received from the device.
-
percent_rh
¶ The converted humidity in %RH.
-
Temperature¶
-
class
sensirion_shdlc_sfa3x.response_types.
Temperature
(ticks)[source]¶ Represents a measurement response for the temperature.
With the
ticks
you can access the raw data as received from the device. For the converted values you can choose betweendegrees_celsius
anddegrees_fahrenheit
.-
__init__
(ticks)[source]¶ Creates an instance from the received raw data.
Parameters: ticks (int) – The read ticks as received from the device.
-
ticks
¶ The ticks (int) as received from the device.
-
degrees_celsius
¶ The converted temperature in °C.
-
degrees_fahrenheit
¶ The converted temperature in °F.
-
Device Errors¶
No Measurement Data Available¶
-
class
sensirion_shdlc_sfa3x.device_errors.
Sfa3xNoMeasurementDataAvailable
[source]¶ No measurement data is available at the moment.
-
__init__
()[source]¶ Constructor.
Parameters: - code (byte) – The error code received from the device.
- message (string) – The error description for the given error code.
-
error_code
¶ Get the error code received from the device.
Returns: Received error code. Return type: byte
-
error_message
¶ Get the description of the received error code.
Returns: Error message. Return type: string
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
Command Not Allowed In Current State¶
-
class
sensirion_shdlc_sfa3x.device_errors.
Sfa3xCommandNotAllowedInCurrentState
[source]¶ The requested command is not allowed in the current device state.
-
__init__
()[source]¶ Constructor.
Parameters: - code (byte) – The error code received from the device.
- message (string) – The error description for the given error code.
-
error_code
¶ Get the error code received from the device.
Returns: Received error code. Return type: byte
-
error_message
¶ Get the description of the received error code.
Returns: Error message. Return type: string
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
File Error¶
-
class
sensirion_shdlc_sfa3x.device_errors.
Sfa3xFileError
[source]¶ A file error occurred (init/read/write error).
-
__init__
()[source]¶ Constructor.
Parameters: - code (byte) – The error code received from the device.
- message (string) – The error description for the given error code.
-
error_code
¶ Get the error code received from the device.
Returns: Received error code. Return type: byte
-
error_message
¶ Get the description of the received error code.
Returns: Error message. Return type: string
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
Fatal Error¶
-
class
sensirion_shdlc_sfa3x.device_errors.
Sfa3xFatalError
[source]¶ An error without specific error code occurred.
-
__init__
()[source]¶ Constructor.
Parameters: - code (byte) – The error code received from the device.
- message (string) – The error description for the given error code.
-
error_code
¶ Get the error code received from the device.
Returns: Received error code. Return type: byte
-
error_message
¶ Get the description of the received error code.
Returns: Error message. Return type: string
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
Commands¶
Start Measurement¶
-
class
sensirion_shdlc_sfa3x.commands.start_measurement.
Sfa3xCmdStartMeasurementBase
(*args, **kwargs)[source]¶ SHDLC command 0x00: “Start Measurement”.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
-
class
sensirion_shdlc_sfa3x.commands.start_measurement.
Sfa3xCmdStartContinuousMeasurement
[source]¶ Start Continuous Measurement Command
Default output format 0.
Note
This command is only available in idle mode.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
Stop Measurement¶
-
class
sensirion_shdlc_sfa3x.commands.stop_measurement.
Sfa3xCmdStopMeasurementBase
(*args, **kwargs)[source]¶ SHDLC command 0x01: “Stop Measurement”.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
-
class
sensirion_shdlc_sfa3x.commands.stop_measurement.
Sfa3xCmdStopMeasurement
[source]¶ Stop Measurement Command
Leaves the measurement mode and returns to idle mode.
Note
This command is only available in measurement mode.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
Read Measured Values¶
-
class
sensirion_shdlc_sfa3x.commands.read_measured_values.
Sfa3xCmdReadMeasuredValuesBase
(*args, **kwargs)[source]¶ SHDLC command 0x03: “Read Measured Values”.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
-
class
sensirion_shdlc_sfa3x.commands.read_measured_values.
Sfa3xCmdReadMeasuredValuesOutputFormat2
[source]¶ Read Measured Values Output Format 2 Command
Read measured values integer.
-
static
interpret_response
(data)[source]¶ Returns: - hcho (int) - Formaldehyde concentration in ppb as a 16-bit signed integer. Positive values only, negative values are coerced to zero. Scale factor 5 ppb^(-1).
- relative_humidity (int) - Relative humidity in %. Values between 0 and 100 only. With internal correction for temperature offset (if configured). Scale factor 100 %^(-1).
- temperature (int) - Temperature in °C. With internal correction for temperature offset (if configured). Scale factor 200 °C^(-1).
Return type: tuple
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
static
Device Information¶
-
class
sensirion_shdlc_sfa3x.commands.device_information.
Sfa3xCmdDeviceInformationBase
(*args, **kwargs)[source]¶ SHDLC command 0xD0: “Device Information”.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
-
class
sensirion_shdlc_sfa3x.commands.device_information.
Sfa3xCmdGetDeviceMarking
[source]¶ Get Device Marking Command
Gets the device marking from the device.
-
static
interpret_response
(data)[source]¶ Returns: String containing the device marking. Return type: str
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
static
Device Reset¶
-
class
sensirion_shdlc_sfa3x.commands.device_reset.
Sfa3xCmdDeviceResetBase
(*args, **kwargs)[source]¶ SHDLC command 0xD3: “Device Reset”.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-
-
class
sensirion_shdlc_sfa3x.commands.device_reset.
Sfa3xCmdDeviceReset
[source]¶ Device Reset Command
Executes a reset on the device.
Note
The device will reply before executing the reset.
-
check_response_length
(data)¶ Check if the response length is correct.
Parameters: data (bytes) – Raw data (payload) received from the device. Raises: ShdlcResponseError – If length is wrong.
-
data
¶ Get the command data (payload).
Returns: Command data (length 0..255). Return type: bytes
-
id
¶ Get the command ID.
Returns: Command ID (0..255). Return type: byte
-
interpret_response
(data)¶ Interpret the response to this command received from the device. This converts the raw byte array to the actual data type(s) depending on the sent command.
Parameters: data (bytes) – Raw data (payload) received from the device. Returns: Interpreted response. Data type and meaning depends on the sent command. None for commands without response data. See the actual command implementation for details.
-
max_response_time
¶ Get the maximum response time for this command.
Returns: Maximum response time in seconds. Return type: float
-
post_processing_time
¶ Get the post processing time for this command. The post processing time defines how long a device needs to execute a command after responding to the SHDLC command. Most devices don’t need post processing (command is executed before the response is sent). Only special commands (e.g. a device reset) are executed after the response is sent.
Returns: Maximum response time in seconds. Return type: float
-