|
Data format for sendings in WiFi/HTTP GSM/HTTP WiFi/MQTT (manual)
By following a few simple rules you can receive data from TXdata, TXtemp, TXsoil and pass data to ControlHUB, DisplayRX, RXTXeasy ... or to your own HTTP or MQTT automation; similarly third party tools can follow these rules to "talk" to ControlHUB, RXTXeasy and so on
|
This manual is interesting for understanding how to send data so that they can be received and processed by
DisplayRX,
RXTXeasy and in particular by the
ControlHUB multifunction controller, especially for the
HTTP part.
Given the large amount of devices that
ControlHUB already supports, hobbyists and professionals alike may find it interesting to interface their stuff (so as not to have to reinvent the wheel).
TXtemp TXdata and
TXsoil, and also
RXTXeasy when it retransmits the data, do already follow the specifications of this page, which are a very basic application of the HTTP and
MQTT standards (so in addition to using these devices with our displays and controllers, you can integrate them into any new or existing automation).
MQTT is supported by most hubs and / or Home Assistant and there are tricks to use it with devices that don't "directly" support it.
HTTP communication <<<
HTTP communication, for its immediacy and the fact that it can also be used easily via GSM, was our first choice. It is not only convenient for
TXtemp TXdata and
TXsoil but it is a smart choice for any new sensor you want to use with
RXTXeasy or interface to a multifunction hub like
ControlHUB.
First we have included this standard in all our devices, and we make it public since for different functions it is still a very practical and efficient choice.
Receiving WiFi / HTTP commands (/c)
The commands can be sent to TXtemp / soil / data via an HTTP GET or POST request made to:
- http://wfeasy.com/c (if you are connected to TXdata / temp / soil internal WiFi)
- or something like http://192.168.1.20/c (if you have connected TXtemp / soil / data to your WiFi; the IP we have exemplified with 192.168.1.20 is usually assigned by the router, TXtemp writes it at the bottom of all the pages once connected; and if you want you can set them inside the configuration options of your router, so that it will not change; typically this is done in a menu such as DHCP utilites or Advanced DHCP).
You can send commands to TXdata / temp / soil in the classic GET request format (and then using the & symbol to insert multiple parameters and separate them, and using the classic "URLencode" to handle non-alphanumeric characters).
The available commands are below.
Example: http://wfeasy.com/c?cm=STATE returns the status (which includes temperature or other data ....)
If you use IP, it will be (for example) http://192.168.1.4/c?cm=STATE and so on.
All this can be tried for example by connecting to the internal WiFi with a PC and by writing these things on the browser bar (Safari, Chrome, Firefox, Explorer); obviously you can also do it with Mac, Raspberry or other devices ...
Command cm=
allows all actions allowed by MQTT commands, with the same command syntax (see below)
Example:
http://wfeasy.com/c?cm=STATE
returns the status of TXdata / temp / soil, which includes the status of the sensor, i.e. temperature, humidity and / or other data
http://wfeasy.com/c?cm=MEM:0
this only works with RXTXeasy and returns the stored status for RF channel 0 entering RXTXeasy (what would be retransmitted as a0)
http://wfeasy.com/c?cm=MEM:100
this only works with RXTXeasy and returns the stored status for WiFi channel 0 incoming to RXTXeasy (the one that would be retransmitted as a100)
Data transmission from TXdata, TXtemp, TXsoil and also RXTXeasy in WiFi / HTTP
In order to send data in HTTP, TXdata, TXtemp or TXsoil format they must be configured in the Settings (see their quick manual on the respective pages:
TXtemp TXdata TXsoil) in order to connect to your WiFi - WiFi which can be a "real" WiFi connected to the Internet or it can also be a
virtual WiFi with virtual web server created by some device (smartphone, PC, Mac, microcontroller, Hub home assistant, ControlHUB, etc.).
Still in the
Settings, the normally preselected configuration is the one for sending HTTP to the other VisualVision products (
SuperClock,
DisplayRX,
ControlHUB and
RXTXeasy GSM); if you want to use your own script on your Web server, choose the next option that allows you to enter the URL of a custom script (it must start with http: // and use the standard port, 80); this option is also good for sending data to a web-facing
ControlHUB.
Generally the script can be something like http://www.aserver.com/nicescript.php or www.aserver.com/nicescript.php. Or nicescript.pl or nicescript.py etc. - any server programming language that supports an HTTP POST request in the normal CGI standard will do.
The name and path of the script on your server is your choice.
If the web server is actually a ControlHUB exposed on the Web, the script must be /x (the default), that is the URL will be like:
http://domainname_or_ip/x
Parameters send by WiFi/HTTP POST CGI and understood by DisplayRX, ControlHUB etc.
All this is also explained in the ControlHUB manual (seen from the receiver's side).
TXtemp TXdata TXsoil (and / or any tool that wants to communicate via HTTP with
DisplayRX ControlHUB etc.), sends, at each transmission, HTTP requests in CGI standard (which are the same ones that are sent when you write something on the browser bar, for example Firefox, Chrome, Safari, Explorer - this means you can send a test transmission to DisplayRX or ControlHUB from the browser) to the indicated URL, GET or POST, with these parameters:
id (unique identifier; preset when the source device is assembled)
pw (password set in the Settings page)
b (battery charge in % - if less than 25 batteries must be replaced)
w (TXdata/temp/soil -> WiFi Channell)
z (RXRXeasy -> WiFi Channell)
n (name - optional, can be omitted)
dm (current frequency / transmission interval: >0 minutes <0 days)
t (TXtemp only-> current temperature * 100)
h (TXtemp only -> current humidity if available)
r (Generic JSON-> {"Temperature":20.1,"Humidity":50,"Pressure":1013.2,"Wind":20.4} ) SEE BELOW AND MQTT
r (TXdata -> current readings, in plain text as HEX to Ascii; TXtemp/soil -> t & h as HexAscii; RXTXeasy -> no)
a0 (RXTXeasy only -> readings retransmitted from 433 Channell #0 format here...)
a1 (RXTXeasy " -> readings retransmitted from 433 Channell #1)
...
a100 (RXTXeasy " -> readings retransmitted from WiFi Channell #0)
a101 (RXTXeasy " -> readings retransmitted from WiFi Channell #1)
...
Example for communication with DisplayRX or SuperClock by using the internal wifi hotspot (this uses Ch WiFi 0, password pippo, other data in the JSON are intuitive):
http://wfeasy.com/x?pw=pippo&w=0&r={"Temperature":20.1,"Humidity":50,"Pressure":1013.2,"Wind":20.4}
Of course if you use spaces and other things use urlencode; if the receiver is on your wifi net you should use its IP instead of the virtual wfeasy.com website name
In case you are sending to your own server / own script rather than to some of our products (DisplayRX and ControlHUB already have a internal server that receives with this standard) that server MUST reply with a short text reply (any reply will be actually read as text; lines terminated by LF), that includes:
- Pass KO if the password is wrong
- RXOK if all right
The server additionally may send these lines followed by LF (\n)
sms=+393475556667
newdm=10
newdm=-2
Meaning: sms=+4432321321321 send immediately a SMS to the number; newdm=10 (newdayminute) set the frequency to 10 minutes; newdm=-2 set the frequency to 2 days.
It will be necessary to enable the operation with "custom script" and the script will be the default one so something like http://2.34.44.39/x or http://something.dyndns.com/x
Legacy Specific things for TXtemp
For a channel receiving a
TXtemp, the data in
r are 2 or 3 bytes in HexAscii
(B1) (B2) (B3):
- temperature=((B1)*256+(B2)) / 100
- (if present) humidity=(B3)
Example for channel 0 in 433: 090A would be temperature 23.14°C or 090A15 would be temperature 23.14 ° C and humidity 21%
Legacy Specific things for TXdata
Assuming to receive a123 = ..., for a channel that receives a
TXdata, the data in
r are:
- the response that the TXdata receives from its command/action (for example a response made up of bytes in HexAscii command / ModBus commands)
Legacy Specific things for TXsoil
For a channel receiving a
TXsoil the data in
r are 2 or 3 bytes in HexAscii
(B1) (B2) [B3]:
- (B1) = 6F (hex)
- humidity=(B2)
Or:
- temperature=((B1)*256+(B2)) / 100 (if there is no temperature measurement, the data could be between -12600 and -12800)
- humidity=(B3)
Example for channel 0 in 433: 6F15 would be humidity 21%
Generic data in JSON (r Generic)
For a channel that receives a generic instrument, the data in r can be either be bytes in HexAscii, or they can be a string in JSON format or the one with braces, e.g. {Temperature:20.3} or also {Energy:20,Volt:220,Ampere:0.34} or {"abc":"something good"}
Now all devices, TXtemp TXsoil TXdata TXloop do transmit in this way; note that Date and Time are omitted if NTP is not activated (after all, the recipient almost always already knows the date and time), this to save time.
Examples:
{"B":77,"Temperature":17.27,"Date":20230520,"Time":1432,"Name":"T595","D":"TXtemp"}
{"B":85,"Temperature":20.34,"Humidity":96,"Date":20230520,"Time":1201,"Name":"S68","D":"TXsoil"}
{"B":92,"Val":0.01,"Date":20230520,"Time":1423,"Name":"L802","D":"TXloop"}
MQTT communication <<<
The information below is specific to
TXtemp TXdata or
TXsoil - however both
DisplayRX and
ControlHUB can interpret a large number of MQTT sources, as long as the message in the MQTT topic is in text, or JSON, or HexAscii.
To have
TXtemp TXdata or
TXsoil data available on an MQTT channel / Topic, you must connect to a WiFi that has access to an
MQTT Broker; for example, you can connect to the laboratory / home / office WiFi, or to the WiFi of a
ControlHUB. This is done from the
Settings, as illustrated in the quick manual. Still in Settings under MQTT you will enter:
- the IP or name of the server where the MQTT Broker runs (if left blank,
TXtemp TXdata TXsoil etc. will not use MQTT)
- eventually username and password of the Broker, if needed
The device shows in the MQTT entry the name of the default topics used for the publication / out and to be used to receive / cmd commands; also you can specify a prefix if you need it (some free brokers require topics to start with for example yourusername/feeds/ or something like that), otherwise leave the "prefix" boxes blank.
Then click Save and TXeasy will connect to the Broker, and after a few seconds it will start working also in MQTT. If the connection is OK it will write OK after the word MQTT; and immediately on the same page you can see the names of the topics to be used to command and receive the
TXtemp TXdata and
TXsoil messages.
For safety, we suggest that you use a Broker installed on a device of yours (PC or other; you can download and install and run a Broker program like Mosquitto even on a simple Windows PC) and possibly NOT to use external clouds / free external brokers because if you do you are potentially putting your things in the hands of strangers.
If the system is not very large you can use the
ControlHUB built-in broker.
MQTT Topic of Response / Publication
When they respond to commands, or when they want to say something,
TXtemp TXdata or
TXsoil post a message on the topic
tx-o-name (where Name is the name given to the device a little further down in the
Settings).
The automation must listen to this Topic in order to read the temperature and / or other data.
The response / payload is a text, this is the text sent periodically to each temperature measurement by TXtemp.
{"B":18,"C":0,"Temperature":23.10,"Date":20230520,"Time":1432,"H":"0906"}
(this curly format is called JSON).
If there is humidity, there will also be a "Humidity" parameter while for TXdata temperature and humidity there are no, to save data Time is not even transmitted, and all data goes to sector H or HexAscii (the meaning of the HexAscii for TXtemp is the same as for HTTP). B is the battery charge in%; C the chosen WiFi channel (even if you already understand from the Topic name which is the TXtemp / data / soil that sends the data, so it is not necessary to set it).
If you turn on
TXtemp TXdata or
TXsoil manually, e.g. for the configuration, a typical message is published on this Topic instead
{"ON":1,"C":0,"Date":20230520,"Time":1432,"H":""}
Topic for Command / Listening
TXtemp TXdata or
TXsoil, when switched on by the user (and not during automatic switching on), listens on the topic
tx-c-name (where Name is the name you gave to your device a little further down in the Settings).
To talk to him, the hub (or anyone by hand through MQTT message sending programs) can publish this message / payload on this Command Topic (which among other things is useful only if you want to keep a
TXtemp TXdata or
TXsoil permanently on).
This feature may be discontinued.
|
STATE or {"STATE"}
|
returns the global status, providing temperature, humidity etc.
|
|
MEM:123 or {"MEM":123}
|
(RXTXeasy only) returns the data stored for a123 (i.e. WiFi channel number 23); available numbers are 0..15 (the 16 RF channels, if present) and 100..199 (which are the WiFi channels from 0 to 99)
|
As known, for
MQTT it is necessary a local or remote system (accessible via the Internet) that is the
MQTT Broker.
If you are doing an automation with
TXtemp TXdata and
TXsoil this can be simplified, and you can avoid this need by using simple HTTP / Web commands instead of MQTT, explained at the top of the page.
Here are the quick manuals for some other products:
(C) 2022 VisualVision
