node-red-umbparser 1.0.2
UMB controller node for meteorological weather stations from Lufft/Ott
UMB controller node
This node can be used to query measurement data from Sensors that support the UMB binary protocol.
The purpose of this node is to periodically poll and parse measurement data from a device. In UMB the measurement values of a sensor/device is organized in channels. The channels to be queried can be configured in the node settings. Furthermore, as every sensors reports the featured channels generically, the node is able to query the channels, that are offered by the sensor dynamically.
UMB protocol details
UMB stands for Universal Measurement Bus. It basically is a RS485 based hardware interface and protocol, that is used by most meteorological sensors from the company by Lufft / OTT Hydromet. The UMB protocol that is used on these sensors is an open standard. There are different variants available for ASCII and binary ouput. This node implements the UMB binary protocol.
For more details about the according sensors and the UMB protocol please visit: https://www.lufft.com/download/manual-lufft-umb-protocol-en/ or https://www.otthydromet.com
What you need to know
Important to know about UMB, is that it is a "Master-Slave" or "Controller-Device" protocol. This means that the bus topoligy featues the connection of different devices but there can only be one controller. The devices are not allowed to send data on the bus themselves. Moreover the Controller sends a request to one device or a group of devices (broadcast). The according device then has a time slot to respond to this request with an according response.
Addressing
Every device on the bus should have an address that is unique.
NOTE: The address consist of a device and a group address. For more details, please refere to the protocol specification, that is mentioned above.
The Controller always has the address 0xF001.
Usage
Input
The input needs ot have no data. It is just used as a trigger to query the configured measurement data.
Output
If the node detects an error, the payload will just contain the according error message.
The output of a properly processed payload consists of mainly two objects:
- parserState This object represents the internal state of the parsed data. Usually this object is set to "finished", which indicates, that the configured requests have been processed properly and an according response was parsed properly.
- umbframe This object contains detailed data of the processed frame
**_Sample output:_**
{
"parserState":"finished",
"umbframe": {
"type":"response",
"payload {"0":0,"1":1,"2":8,"3":0,"4":100,"5":0,"6":22,"7":69,"8":177,"9":142,"10":64 },
"cmd":47,
"status":0,
"crc":8566,
"FromAddr":28673,
"ToAddr":61441,
"framedata": {
"name":"Multi channel data",
"raw":[ {
"ch_number":100,
"ch_data_type":"FLOAT",
"ch_status":0,
"ch_value":4.459139347076416
}],
"parsed":{
"Temperature":"4.46"
}
}
}
}
umbframe details
the umbframe object contains all the parsed information:
type "response" or "request".
NOTE: With this node this will be always "response"
payload Raw payload data that can be used for debugging.
cmd Parsed UMB command
status
Parsed UMB status
crc CRC within the UMB frame. The CRC is always parsed and verified. If a frame CRC error is detected this is reported in an according parserState. Hence, this value is only set, when the UMB framing including the CRC was correct.
FromAddr
Address of the devices that sends the response
ToAddr
The address of this node.
NOTE: As this node is designed to be the controller in the UMB setup, this value will alwys be "0xF001"/"61441"
framedata This object contains more detailed information about the data that has been received.
framedata details
The framedata object contains information that will be important for most applications.
The internal UMB parser of this node is generally able to parse multiple different response types. But as this node mainly is designed to query for measurement data, the response will mostly be a "Multi channel data" response. This response contains all the measurement data that has been configured accordingly.
Besides the name, this object contains the raw data and the parsed data of the response.
The raw object contains an array of the measurement channels that have been queried.
The parsed object contains the parsed data.
msg.payload.umbframe.framedata.parsed: {
"Temperature":"4.46",
"Humidity":"78.2"
}
NOTE: Please note that parsing only works properly when you have selected unique channels. Most devices feature identical channels for different unit systems. If you have selected the same measurement (e.g. temperature) with different units (°C and °F) the node will report an according warning, as both measurement values would be parsed with the same measurement name (in this example "Temperature").
Configuration
The basic configuration of the node includes:
- Name
- Device Address
- Device IP
- Channels This channel configuration is a separate configuration, that defines a set of measurement channels to be queried.
Channel configuration
Each channel definition consists of 3 values:
- a channel ID - indicated with a # at the begining
- a channel name - is automatically queried or can be modified manually
- A Unit - defines the unit of the acoording meausrement
The check box at the left of each measurement activates or deactivates the channel.
A measurement channel can be deleted from the configuration using the cross at the right side of the measurement entry.
Add channel manually
Below the channel list is a + button that allows you to add channels as you need.
Query device channels
The download button right beside the Channels label can be used to query a new channel list from the device. As there very often exist multiple measurement channels with different units, e.g. Temperature in °C and °F, you may select the according unit system used in your application.
NOTE: Please note that all existing channels will be deleted when retrieving a new channel list from the device.
Query measurement channels from the device
NOTE: Please note that the device must be powered to query the supported channels.
The configured channels will be queried from the device, everytime the input port is triggert. The input data is not evaluated.
Known issues
FAQ
Q: I get a "multiple measurements" warning A: Please verify that you don't query multiple channels with the same name (e.g. different units). See [frame details](#frame details) description
Bugs
No bugs are known yet.
Planned features
Serial interface support
Currently the node only support IP socket queries via TCP. Depending of the device, node-red is running a direct serial interface might be more useful, especially as there are only a few device from OTT Hydromet that feature ethernet or WiFi interfaces.
Implement status request feature to ping a device
Every UMB device features a status command, that can be used to ping a device. This is helpful to verify that the basic configuration and setup is working properly.
