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

device_reset()[source]¶: Execute a device reset (reboot firmware, similar to power cycle).

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.

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 with False 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 the ppb 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 the percent_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 between degrees_celsius and degrees_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”.

__init__(*args, **kwargs)[source]¶: Constructor.

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.

__init__()[source]¶: Constructor.

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”.

__init__(*args, **kwargs)[source]¶: Constructor.

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.

__init__()[source]¶: Constructor.

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”.

__init__(*args, **kwargs)[source]¶: Constructor.

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.

__init__()[source]¶: Constructor.

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

Device Information¶

class sensirion_shdlc_sfa3x.commands.device_information.Sfa3xCmdDeviceInformationBase(*args, **kwargs)[source]¶

SHDLC command 0xD0: “Device Information”.

__init__(*args, **kwargs)[source]¶: Constructor.

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.

__init__()[source]¶: Constructor.

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

Device Reset¶

class sensirion_shdlc_sfa3x.commands.device_reset.Sfa3xCmdDeviceResetBase(*args, **kwargs)[source]¶

SHDLC command 0xD3: “Device Reset”.

__init__(*args, **kwargs)[source]¶: Constructor.

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.

__init__()[source]¶: Constructor.

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