Due to the insufficient documentation in ioBroker, I am no longer compelled to maintain this adapter.
Method "createState" is deprecated and will be removed in js-controller 7.1, use "extendObject/setObjectNotExists" (Issue #24)
createState extendObject setObjectNotExists
The entire extent of the documentation is this:
- extendObject = function extendObject(id, obj, callback)
- setObject = function setObject(id, obj, callback)
- setObjectNotExists = function setObjectNotExists(id, object, callback)
How to write object To write the objects generally two functions can be used: setObject, setForeignObject. But there are many help functions to modify objects:
extendObject, extendForeignObject, delObject, delForeignObject, setObjectNotExists, setForeignObjectNotExists createDevice, deleteDevice createChannel, deleteChannel, createState, deleteState addStateToEnum, deleteStateFromEnum extendObject is just reads object, merges with given one and write object back.
Difference between xxxObject and xxxForeignObject is that xxxObject automatically extends the object id with "adapter.instance." text.
Functions are always asynchronous.
adapter.getForeignObject('otherAdapter.X.someState', function (err, obj) {
if (err) {
adapter.log.error(err);
} else {
adapter.log.info(JSON.stringify(obj));
obj.native = {}; // modify object
adapter.setForeignObject(obj._id, obj, function (err) {
if (err) adapter.log.error(err);
});
}
});
Yep, that's what was given to replace createState. I spent an hour, frustrated for not getting anywhere I gave up and forgot about it. Why does the depreciated function have way better documentation than the recommended one? Why doesn't the recommended one have any documentation at all? Then, ioBroker members started contacting me. I asked further questions, no one could offer any help. It seems like they do not want to make it easy for people to develop adapters anymore.
FUBAR
I have three recommendations for those looking for this:
- Stick a fork in it and fix it yourself - fluency in German and hacking recommended.
- Give up on ioBroker, it is obvious HomeAssistant has won this battle.
- rtl_433 -> mqtt utility from GitHub
To make breaking changes to the underlying API of a home automation application is the kind of garbage that made me walk away from OpenHAB and come to ioBroker. Alas, ioBroker is now even worse. If I rebuild this adapter, it won't be for ioBroker
This adapter allowed you to integrate data from the airwaves into ioBroker using an inexpensive RTL-SDR USB stick. These are built around chips originally used to tune in analog TV signals but are now used as software defined radios. 433 MHz is a common frequency as it is open in the US. The software defined radio is capable of tuning in most of the open frequency bands, the parameters of this adapter allow you to configure the frequency you need.
You can use multiple RTL-SDR dongles to monitor multiple frequencies by setting up more than one instance of iobroker.rtl_433. Options are available to use the native index of the device to rtl_433, the USB port, a TCP/IP address and others as supported by the rtl_433 utility.
The reason for the 433 in the name is that the adapter requires the utility rtl_433 to be installed and runnable on the host computer. All the remote sensors that can be integrated with this adapter are read from the utility and displayed in the protocols tab. As is often the case with USB adapters the device might not be ready the first time it tries to start and may compain about LIB_USB or other USB errors, this is not to be generally worried about - it should start with a minute.
This is a work in progress. I do not have a full set of keys that rtl_433 uses to generate its JSON but I have gone through the test cases on the project collecting most of the possible keys. If a data type is not recognized it will simply be imported as string/value. The keys of responses supported can easily be extended by modifying lib/datapoints.js. Setting the logging to debug for the adapter will show the JSON formatted data from the rtl_433 program.
Note: The meta-data includes an alive state. This is only pertinent to devices that radio their data frequently like thermometers and not to be a cause for concern on devices that radio their data infrequently like contact sensors.
You can read a remote sensor! To do so you would only need to install rtl-sdr on the remote computer with a rtl-sdr dongle. Using a Raspberry Pi as the remote you would do a fresh install, update it, then run
sudo apt-get install rtl-sdr
After it is installed you would connect the rtl-sdr adapter on it then run
rtl_tcp -a `hostname -I | awk '{print $1}'`
Then in the setup pages of the iobroker.rtl_433 adapter put in the device type of TCP/IP and enter the ip:port of the Pi. Note: if you omit the port it will assume port 1234. When the adapter restarts it will connect to the remote sensor to get the data.
You can enter multiple frequencies into the frequency input in the options tab separated by a comma or whitespace
344975000 433920000
this will tell the rtl_433 utility to hop between those frequencies. The default hop interval is 600 seconds but that can be changed in the hop frequency input just below the frequency input.
Based on the feedback I have improved the admin pages to be much more comprehensive. This should help to alleviate the issues I have seen so far.
- Make sure rtl_433 runs from the command line.
- Make sure it can run from the command line as the iobroker user.
- If you contact me, please include the following:
- version - the version from the main admin page.
- rtl_433_cmd - the command line from the main admin page.
- any pertinent logs
If you are experiencing trouble with a specific device, please let me know the output for that device using 'rtl_433 -F json' so I can figure out what the program is doing when the device transmits.
- "include" feature to capture your own then stop the creation of new devices, other coniguration changes
- automatically add missing states to existing device, helps future proof the adapter. Added protocol to INFO, can be used to know what the device is capable of.
- This has been operating successfully for over a half a year on my local installation. I have decided to move it to 1.0 designation with full ioBroker package compliance and registration
- Fixed internationalization of admin page labels as well as a few initializattion problems
- Improved the administration pages to be both more flexable and informative.
- Changed how the adapter instanciates the rtl_433 utility for stability purpose.
- Fixed many errors in the internationalization
- a few teaks for converting the old configuration
- a few more fixes
- Fixed frequency hopping use in the configuration. Fixed a bug that crashed the adapter if an object was not correctly created. Hardened the ioBroker interface to errors with heavy use of try/catch and logging.
- Explicitly added ack=true to the setState commands to eliminate warnings in the logs, fixed bad selector that lost protocols when not on the protocols tab, updated dependencies.
- In previous versions I only recorded values that differed from the previous value. Now you have an option to de-duplicate the values or not. Updated dependencies.
- Fixed the error about "parentChannel" and updated dependencies
MIT License
Copyright (c) 2021 Sean Phillips [email protected]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright (c) 2021 Sean Phillips [email protected]