pimatic-radiohead by Peter Müller (crycode) | github | npm

pimatic-radiohead

pimatic-radiohead is a pimatic plugin that integrates RadioHead into pimatic.

With pimatic-radiohead you are able to include pimatic into your RadioHead network using a serial interface. You may also use a small microprocessor (e.g. an Arduino nano) as a serial-radio-gateway to include some radio hardware.

Build you own bus system based on pimatic, RS485 and radio devices!

RadioHead is a open source Packet Radio library for embedded microprocessors. It provides addressed, reliable, retransmitted, acknowledged variable length messages.

pimatic-radiohead uses the radiohead-serial Node.js module.

German version of this readme: README-de.md

Attention: Since v2.0.0 this plugin requires at least Node.js v8.9!

Features

Receive messages/commands from other nodes in you local RadioHead network.
Send messages/commands to other nodes in you local RadioHead network.
Devices to show and process messages received from other nodes.
Devices to send messages to other nodes.
Rules are supported for triggering actions and sending messages including variables.
Device attributes give you some statistics about sent and received messages.
Multiple RadioHead networks are supported using different serial interfaces.

Device configuration localized in:

en - English
de - German

Devices

All device configuration can be done using the pimatic frontend.

A detailed description of all config options is available in the file device-config-schema.coffee.

RadioHeadSerialPort

This is a special device, which provides the interface to the serial hardware.

It is needed for all other devices.

By default only messages addressed to this node or the broadcast address are handled. You may activate the promiscuous mode to handle messages with any to address.

RadioHeadContactSensor

A ContactSensor based on received messages.

You need to define some data bytes, which have to match a received messages for the closed and opened action. An automatic reset is also possible, if the sending device only emits one action.

RadioHeadPresenceSensor

A PresenceSensor based on received messages.

You need to define some data bytes, which have to match a received messages for the present and absent action. An automatic reset is also possible, if the sending device only emits one action.

RadioHeadSwitch

A Switch which sends configurable messages if turned on or off.

RadioHeadShutter

A ShutterController which sends configurable messages if moved up, moved down or stopped. An automatic stop is also possible, if you wish to stop after a specific time.

RadioHeadButtonsDevice

A ButtonsDevice to provide some buttons. One button can send and/or receive messages.

You may use this device to send a message if the user clicks a button in the frontend.

You may also use this device to handle some buttons from a remote control.

RadioHeadWeatherStation

A Sensor which can receive and display various weather information.

You are able to define multiple data messages to extract the values. Each value can be preprocessed by an expression to manipulate the received value.

Values which consists of more than one byte can be in Little-Endian (LE) or Big-Endian (BE) format.

Supported data types in a message are: 32bit Float LE, 64bit Double LE, 8bit Integer, 8bit Unsigned Integer, 16bit Integer LE, 16bit Unsigned Integer LE, 32bit Integer LE, 32bit Unsigned Integer LE, 4bit Float BE, 8bit Double BE, 16bit Integer BE, 16bit Unsigned Integer BE, 32bit Integer BE, 32bit Unsigned Integer BE

Use the following indicators to mark the positions of the values in the data messages:

t - temperature
h - humidity
r - rain
ws - wind speed
wd - wind direction
wg - wind gust
b - battery status
lb - low battery

RadioHeadCustomSensor

A Sensor which can receive and display various numeric and boolean data.

You can define multiple custom numeric and boolean sensor values and you are able to define multiple data messages to extract the values. Each numeric value can be preprocessed by an expression to manipulate the received value.

Values which consists of more than one byte can be in Little-Endian (LE) or Big-Endian (BE) format.

Use you own or the following predefined indicators to mark the positions of the values in the data messages:

b - battery status

Rule syntax and examples

Predicates (when ...)

You may use the following conditionals to trigger a rule:

radiohead [received] "<dataBytes>" from <senderAddress> [to <recipientAddress>] using <device>

received - Optional word for better readability.
dataBytes - The received data bytes in hex notation, separated by spaces. You may use a * as wildcard to accept any byte at this position.
senderAddress - The address of the sending node in the RadioHead network in hex notation. You may use 0xFF to accept all senders.
recipientAddress - Optional. The address of the receiving node in the RadioHead network in hex notation. If omitted, the own address of the device will be used. Useful for broadcasts or if the RadioHeadSerialPort device is used in promiscuous mode.
device - ID or name of the RadioHeadSerialPort device which is used.

Examples

radiohead received "0x01 0x02 0xAB" from 0x05 using rh-serial-1

radiohead received "0x01 0x02 0xAB" from 0x05 to 0x01 using rh-serial-1

radiohead "0x63 0x72 0x79 0x43 0x6F 0x64 0x65 * 0x64 0x65" from 0xFF using rh-serial-1

Actions (then ...)

You may use the following action in a rule:

[send] radiohead "<dataBytes>" to <recipientAddress> using <device>

send - Optional word for better readability.
dataBytes - The data bytes in hex notation to send, separated by spaces. You may also use variables as described below.
recipientAddress - The address of the receiving node in the RadioHead network in hex notation. Use 0xFF for broadcast messages.
device - ID or name of the RadioHeadSerialPort device which is used.

Examples

send radiohead "0x01 0x02 0xAB" to 0x05 using rh-serial-1

radiohead "0x63 0x72 0x79 0x43 0x6F 0x64 0x65" to 0xFF using rh-serial-1

send radiohead "0x55 $my_var d$my_double_var i$my_int_var b$my_boolean_var" to 0x42 using rh-serial-1

Variables in Actions

You can include pimatic variables in the data bytes as well as static byte values.

There are some modifiers to define the datatype of the transmitted variable content. A modifier is a single letter, which is prefixed to the variable name.

Without any modifier a variable will be sent as one byte, representing the 8-bit unsigned integer value of that variable.
i - 32-bit integer
I - 16-bit unsigned integer
d - 64-bit double
f - 32-bit float
b - boolean (false=0x00, true=0x01)

All variables will be sent using little-endian format.

Example

"0x01 $my_var d$my_temperature" will sent 10 bytes: One byte with the fixed value 0x01, one byte representing the 8-bit value of $my_var and 8 bytes representing the temperature saved as double in $my_temperature.

Attributes

The following attributes are provided by each RadioHeadSerialPort device as pimatic variables:

sentOkCount - The count of successfully sent messages since the last start.
sentErrorCount - The count of faulty sent messages since the last start.
receivedCount - The count of received messages since the last start.
retransmissionsCount - The count of retransmitted messages since the last start. High values indecat problems (e.g. bus collisions or unreachable devices).

Debug

You can enable the debug mode in the plugin config.

In debug mode you will find all received RadioHead messages in the log and some other additional information, e.g. about matched data for the devices.

License

Licensed under GPL Version 2

Some parts of the RadioHeadWeatherStation devices are inspired by pimatic-homeduino.

Plugin Config Options

RadioHead config options

Option	Description	Default
debug boolean	Enable debug output	false

Device Config Options

RadioHead device config schemes

RadioHeadSerialPort

RadioHeadSerialPort config options

Option	Description	Default
port string	The serial port used for the communication.	"/dev/ttyUSB0"
baud integer	The baud rate used for the communication.	9600
address string	The address of this node in the RadioHead network in hex or dec. (0x00 to 0xFE)	"0x01"
promiscuous boolean	Tells the receiver to accept messages with any to address, not just messages addressed to this node or the broadcast address.	false
reliable boolean	Use the manager 'RHReliableDatagram' (true) or 'RHDatagram' (false).	true
retries number	The maximum number of retries for sending a message. If set to 0, each message will only ever be sent once.	3
timeout number	The minimum retransmit timeout in milliseconds. If an ack is taking longer than this time, a message will be retransmitted.	200

RadioHeadContactSensor

RadioHeadContactSensor config options

Option	Description	Default
radioHeadSerialPort string	The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
fromAddress string	The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.
toAddress string	The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.	""
dataClosed array of strings	Array with the data bytes of the message in hex or dec for the 'closed' action. Use * to ignore specific data bytes.	[]
dataOpened array of strings	Array with the data bytes of the message in hex or dec for the 'opened' action. Use * to ignore specific data bytes.	[]
autoReset boolean	Reset the state after resetTime. Useful for contact sensors, that only emit open or close events.	false
resetTime integer	Time in ms after that the contact state is reseted.	1000

RadioHeadPresenceSensor

RadioHeadPresenceSensor config options

Option	Description	Default
radioHeadSerialPort string	The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
fromAddress string	The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.
toAddress string	The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.	""
dataPresent array of strings	Array with the data bytes of the message in hex or dec for the 'present' action. Use * to ignore specific data bytes.	[]
dataAbsent array of strings	Array with the data bytes of the message in hex or dec for the 'absent' action. Use * to ignore specific data bytes.	[]
autoReset boolean	Reset the state after resetTime. Useful for contact sensors, that only emit open or close events.	false
resetTime integer	Time in ms after that the contact state is reseted.	1000

RadioHeadSwitch

RadioHeadSwitch config options

Option	Description	Default
radioHeadSerialPort string	The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
toAddress string	The address of the receiving device in the RadioHead network in hex or dec. Use 0xFF for broadcasts.
dataOn array of strings	Array with the data bytes of the message in hex or dec for the 'on' action.	[]
dataOff array of strings	Array with the data bytes of the message in hex or dec for the 'off' action.	[]
defaultState boolean	State to set on startup, if not given, last state will be restored

RadioHeadShutter

RadioHeadShutter config options

Option	Description	Default
radioHeadSerialPort string	The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
toAddress string	The address of the receiving device in the RadioHead network in hex or dec. Use 0xFF for broadcasts.
dataUp array of strings	Array with the data bytes of the message in hex or dec for the 'move up' action.	[]
dataDown array of strings	Array with the data bytes of the message in hex or dec for the 'move down' action.	[]
dataStop array of strings	Array with the data bytes of the message in hex or dec for the 'stop' action.	[]
autoStopTimeUp integer	Time in milliseconds after which moving up should stop automatically (e.g. 20000). Disabled if using default or 0.	0
autoStopTimeDown integer	Time in milliseconds after which moving down should stop automatically (e.g. 20000). Disabled if using default or 0.	0

RadioHeadButtonsDevice

RadioHeadButtonsDevice config options

Option

Description

Default

radioHeadSerialPort
string

The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.

buttons
array of objects

The Buttons.

[]

Elements

Option	Description	Default
id string	The ID of this button. This must be unique.
text string	The text of this button. This will be shown in the frontend.
send boolean	Enable sending with this button. You must also set 'toAddress' and 'dataSend'.
sendToAddress string	The address of the receiving device in the RadioHead network in hex or dec. Use 0xFF for broadcasts.	""
dataSend array of strings	Array with the data bytes of the message in hex or dec for sending.	[]
receive boolean	Enable receiving with this button. You must also set 'fromAddress' and 'dataReceive'.
receiveFromAddress string	The from address of a received message in hex or dec. Use 0xFF for all senders.	""
receiveToAddress string	The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.	""
dataReceive array of strings	Array with the data bytes of the message in hex or dec for receiving. Use * to ignore specific data bytes.	[]

RadioHeadWeatherStation

RadioHeadWeatherStation config options

Option	Description	Default
radioHeadSerialPort string	The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
fromAddress string	The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.
toAddress string	The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.	""
data array of arrays	You may add multiple messages, if your device is sending different messages for each data.
temperature	The datatype of the transmitted temperature or 'none' if no temperature is used.	"none"
temperatureUnit string	The unit of the temperature.	"°C"
temperatureProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"
humidity	The datatype of the transmitted humidity or 'none' if no humidity is used.	"none"
humidityUnit string	The unit of the himudity.	"%"
humidityProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"
rain	The datatype of the transmitted rain fall or 'none' if no rain fall is used.	"none"
rainUnit string	The unit of the rain fall.	"mm"
rainProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"
windSpeed	The datatype of the transmitted wind speed or 'none' if no wind speed is used.	"none"
windSpeedUnit string	The unit of the wind speed.	"m/s"
windSpeedProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"
windGust	The datatype of the transmitted wind gust or 'none' if no wind gust is used.	"none"
windGustUnit string	The unit of the wind gust.	"m/s"
windGustProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"
windDirection	The datatype of the transmitted wind direction or 'none' if no wind direction is used.	"none"
windDirectionProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"
battery	The datatype of the transmitted battery status or 'none' if no battery status is used.	"none"
batteryProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"
lowBattery	The datatype of the transmitted low battery status or 'none' if no low battery status is used.	"none"
lowBatteryProcessing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"

RadioHeadCustomSensor

RadioHeadCustomSensor config options

Option

Description

Default

radioHeadSerialPort
string

The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.

fromAddress
string

The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.

toAddress
string

The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.

""

battery

The datatype of the transmitted battery status or 'none' if no battery status is used.

"none"

batteryProcessing
string

Expression that can preprocess the value, $value is a placeholder for the value itself.

"$value"

customValues
array of objects

You may add multiple custom numeric sensor values.

Elements

Option	Description	Default
id string	ID of this custom value. Must be unique at this custom sensor. (e.g. 'myTemperature')
indecator string	Indecator used in the set data bytes to identify this value. Must be unique at this custom sensor. (e.g. 't')
unit string	The unit of this sensor value. (e.g. '°C')
acronym string	The acronym for this sensor value. (e.g. 'T')
displaySparkline boolean	Should a sparkline be displayed for this sensor value?	true
recvDataType	The datatype of the received sensor value.
processing string	Expression that can preprocess the value, $value is a placeholder for the value itself.	"$value"

customBooleans
array of objects

You may add multiple custom boolean sensor values.

Elements

Option	Description	Default
id string	ID of this custom value. Must be unique at this custom sensor. (e.g. 'myValue')
acronym string	The acronym for this sensor value. (e.g. 'P')
labelTrue string	The label for a 'true' value. You may use unicode symbols like ✔.	"On"
labelFalse string	The label for a 'false' value. You may use unicode symbols like ✘.	"Off"
dataTrue array of strings	Array with the data bytes of the message for a 'true' value in hex or dec. Use * to ignore specific data bytes.	[]
dataFalse array of strings	Array with the data bytes of the message for a 'false' value in hex or dec. Use * to ignore specific data bytes.	[]

data
array of arrays

You may add multiple messages, if your device is sending different messages for each data.

pimatic-radiohead is written by Peter Müller (crycode)