___ _____ _ _ __________ __ __ _
|_ _|__|_ _| | || ||___ /___ /| \/ | |__ ____
| |/ _ \| |_____| || |_ |_ \ |_ \| |\/| | '_ \|_ /
| | (_) | |_____|__ _|__) |__) | | | | | | |/ /
|___\___/|_| |_||____/____/|_| |_|_| |_/___|
Iot-433mhz is a home automation framework for 433mhz devices that runs on node.js. You can control 433MHz RC power sockets, PIR sensors, Door Sensors and much more. To get started you just need a:
For more about the required 433mhz transmitter/receiver and the supported hardware see the hardware-layer page.
You can get it on npm:
npm install iot-433mhz -g
and then execute it from console with:
iot-433mhz
or Clone this Repo:
git clone https://github.com/roccomuso/iot-433mhz.git
Then don't forget to use the right Node version (install nvm to handle Node.js versions) and install all the dependencies.
Tested and fully-working with Node 6.17.1
and Yarn 1.10.0
:
nvm install 6.17.1
npm i -g yarn@1.10.0
yarn install
Heads Up: On Raspberry Pi, you can encounter some issue installing all the dependencies, due to permission errors. If that happens try this: sudo chown -R $USER:$GROUP ~/.npm
combined with running npm cache clean
to get any busted packages out of your cache. In addition, if the error still persist, try adding the flag --unsafe-perm
:
sudo npm install --unsafe-perm (if installing from git)
or
sudo npm install iot-433mhz -g --unsafe-perm (if installing from npm)
Note: the reason for using the --unsafe-perm
option is that when node-gyp tries to recompile any native libraries (eg. serialport) it tries to do so as a "nobody" user and then fails to get access to certain directories. Allowing it root access during install allows the dependencies to be installed correctly during the upgrade.
If running on different platforms follow the platform-specific setup below:
![]() |
![]() |
![]() |
![]() |
![]() |
---|---|---|---|---|
IE 11+ ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ |
Iot-433Mhz is built on top of Node.js. The server is multi-platform, can run on different hardware combinations shown below:
The iot-433mhz server should run smoothly. Remember to install with root permission (sudo):
sudo npm install iot-433mhz -g
and then execute with:
iot-433mhz
To run the server on windows make sure to install python 2.7 and Microsoft Visual Studio Express 2013. (Required by node-serialport). Then just do a:
npm install iot-433mhz -g
and then execute with:
iot-433mhz
To use iot-433mhz on Raspberry Pi first do a system update:
/etc/apt/sources.list
to have jessie
wherever you've currently got wheezy
.sudo apt-get update && sudo apt-get dist-upgrade
.sudo rpi-update
.Then install Node.js:
wget http://node-arm.herokuapp.com/node_latest_armhf.deb
sudo dpkg -i node_latest_armhf.deb
# Check installation
node -v
One way to go is directly connecting the radio transmitter and receiver to the GPIO as shown in the following picture, but first remember to install wiringPi (link) and to execute the app with root permission (sudo):
Heads Up. The RF receiver module operates at 5V. THE GPIO data pins can only support 3.3V! If you put your receiver on 5V, the data io pin of the raspberry will also receive 5V which is way too high. A simple resistor (4.7k) should be fine, as already outlined in many forum posts, but is recommendend a logic level converter / level shifter or a simple voltage divider:
here the voltage divider:
The important thing here is the ratio of R1 to R2; R1 should be just over half R2's value to ensure 5V is divided down to 3.3V. The values shown here should be suitable for most uses.
NB. For this configuration the Raspberry Pi platform uses the 433mhz-utils library through the rpi-433 module. But notice that RFSniffer (compiled c) appears to chew up all the RPi CPU (95%). Not ideal at all, therefore an external Arduino is the recommended solution.
The system can run on RPi using an external Arduino like the other platforms. To do that, just set to true
the use-external-arduino
option in the config.json
file.
In this way we'll force the RPi to use an Arduino through USB, using the node.js serialport module.
I'm not sure if strictly necessary but it's worth installing the arduino IDE and related drivers with apt-get install arduino
.
Heads Up! Sometimes the USB doesn't get detected on the fly (you should be able to see it with ls /dev/tty*
- USB not working?). Just plug-it and then reboot your RPi.
Is recommended to run the server on the RPi through a "terminal session". (see screen).
Through the Settings page from the Web Interface, you can more or less change the general settings (stored in config.json
). Few of those settings are there listed with their default values:
DEBUG: true, // Start the app in Debugging mode.
username: root, // Username required to authenticate (required also during API calls)
password: root, // Password required to authenticate (required also during API calls)
arduino_baudrate: 9600, // The arduino default baudrate (no need to change it)
server_port: 8080, // Choose on which port you wanna run the web interface
db_compact_interval: 12, // Database needs to be compacted to have better performance, by default every 12 hours it will be compacted, put 0 to avoid DB compacting.
"backend_urls": "..." // You can specify a backend json file containing the urls to carry out notifications. (NB. this requires the iot-433mhz-backend repo)
iot-433mhz makes use of the node DEBUG module. It's enabled by default, but you can enable or disable it using the environment variable DEBUG=iot-433mhz:*
. You could also debug a specific part of the application providing as secondary param the file name, like DEBUG=iot-433mhz:socketFunctions.js
.
If you made a change to the settings from the Web interface, then to make it effective, you need to restart the app. The best way to set custom settings is through the CLI optional parameters, shown below.
Start the system with the console global command:
iot-433mhz
Then you'll have to select the correct serial port to which the Arduino is attached to
Once selected you're ready to go! You're then free to use the system through the beautiful web interface (thumbs up for material-design) or use the API to build your own interface.
To custom your system settings simply use the CLI options:
iot-433mhz --help
That shows something like that:
You can provide some parameter also as ENV variables:
NODE_ENV=development # for virtual serial port
PORT=8080 # web server port
SERIAL_PORT=/dev/ttyUSB0 # serial port
Reachable on the http://serverAddress:PORT
, the web server_port
is defined in config.json
, default's value is 8080. It works well in browsers like Chrome (reccomended), Firefox, Safari, Opera, Microsoft Edge (it doesn't on Internet Explorer, avoid it).
It also announce itself over mdns on the address iot-433mhz.local
, so you don't have to struggle to get the server ip address.
Once you open the address on your browser an authentication is required. Username and password are stored inside the config.json file (default values are: root, root).
If you wanna have a live console output of your iot-433mhz running on Node. There's a real time console-mirroring web-console on http://serverAddress:PORT/console.html
. (Thanks to console-mirroring).
The web interface provides along with supported browsers the ability to add the page on your homescreen like a native application. The first time you'll open it, a pop up will come out.
Heads Up! If your server is running on a RPi, make sure to have a static ip address assigned to your server. Otherwise the linked app on the homescreen will not work anymore.
See the Hardware page.
Below every single API available is documented. Too lazy to copy and paste? just download and import the Postman collection (download).
Tip: The iot-433mhz server requires a basic Authentication also for the API calls. Username and Password are defined inside the config.json file (default username and password: root, root). What you need to take into account is to set the following header field during your HTTP requests: Authorization: Basic cm9vdDpyb290
where the last string is the base64 encoding of root:root
, if you changed default username and password you should update the base64 text too (learn more on Basic Authentication Access).
GET /api/settings/get
Return the current settings. Useful to see notification status.
GET /api/system/get/uid
Return the unique IoT System UID (a unique random ID generated from the system).
GET /api/system/new/uid
Generate a new unique IoT System UID (a unique random ID generated from the system).
GET /api/system/telegram/enable
Enable notification through Telegram Bot.
GET /api/system/telegram/disable
Disable notification through Telegram Bot.
GET /api/system/email/enable
Enable notification through Email.
GET /api/system/email/disable
Disable notification through Email.
GET /api/code/send/[RFcode]
send the specified rfcode. Return a status object: {"status": "ok"}
or {"status": "error", "error": "error description.."}
GET /api/codes/ignored
Return a list of ignored codes stored in DB.
GET /api/codes/all
Return all the registered codes stored in DB.
GET /api/codes/available
Return all the available codes stored in DB. Available codes can be assigned to a new device card.
GET /api/cards/all
Return all the cards stored in DB.
GET /api/cards/get/[shortname]
Return a single card with the specified shortname.
POST /api/cards/new
form-data required parameters:
headline - a brief headline.
shortname - lower case, no spaces.
card_body - a description, html allowed.
room - lower case, no spaces.
type - must be one of the following types: switch/alarm/info
device - if type==switch gotta have on_code and off_code parameters. if type==alarm just the trigger_code parameter
Optional parameter: card_img
, background_color
(must be an hex color with).
Json response: 200 OK - {"done": true, "newCard": ...}
where newCard is the json card just inserted. Or {"done": "false", "error": "error description..."}
GET /api/cards/delete/[shortname]
Delete the card with the specified shortname, it returns {"status": "ok", cards_deleted: 1}
or {"status": "error", "error": "error description.."}
POST /api/cards/arm-all
Arm all the alarm type cards. It returns {"status": "ok", cards_affected: n, armed: true}
or {"status": "error", "error": "error description.."}
POST /api/cards/disarm-all
Disarm all the alarm type cards. It returns {"status": "ok", cards_affected: n, armed: false}
or {"status": "error", "error": "error description.."}
GET /api/alarm/[shortname]/arm
Only alarm type cards can be armed.
GET /api/alarm/[shortname]/disarm
Only alarm type cards can be disarmed. (If disarmed no WebHook callbacks or any kind of notifications will be sent)
GET /api/switch/[shortname]/on
Turn on a switch.
GET /api/switch/[shortname]/off
Turn off a switch
GET /api/switch/[shortname]/toggle
Toggle a switch
Webhooks allow you to build or set up integrations which subscribe to certain events on the iot-433mhz system. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. (thanks to node-webhooks) Webhooks can be used to catch several events:
NB. In this current release WebHooks are not card-specific. For example, a single alarmTriggered event type catches every alarm trigger. It's up to you parse the payload and make sure that was the sensor you were wishing for.
Use the API below to set up and interacts with WebHooks.
POST /api/webhook/add/[WebHookShortname]
Add a new URL for the selected webHook.
Required parameters:
webHookShortname - Provided in url, it must be one of these*: alarmTriggered, newCard, cardDeleted, newCode, switchToggle.
url - the URL to which a HTTP POST request will be sent when the event get fired (the request carries a JSON payload field that gotta be parsed).
Let's describe every event JSON payload you're gonna listen for according to the supplied webHookShortname
:
alarmTriggered = {"card_id": "...", "last_alert": 1453..., "code": ..., "shortname": "...", "room": "..." }
* NB. an alarmTriggered WebHook callback will be executed only if the alarm card is armed!
newCard = {"card_id":"...", "headline": "", "shortname": "", "card_body": "", "img": "", "type": "switch/alarm/info", "room": "", "device": { *** }}
NB. device depends on type: if switch, we would look for these properties: on_code, off_code, notification_sound, is_on. If alarm: last_alert, trigger_code, notification_sound. If info device got no properties.
cardDeleted = {"card_id": "..."}
newCode = {"code": "...", "bitlength": ..., "protocol": ...}
NB. The detected code could be ignored or already attached to a device card.
switchToggle = {"card_id": "...", "is_on": true/false, "sent_code": ..., "timestamp": 1453... }
GET /api/webhook/get
Return the whole webHook DB file.
GET /api/webhook/get/[WebHookShortname]
Return the selected WebHook.
GET /api/webhook/delete/[WebHookShortname]
Remove all the urls attached to the selected webHook.
POST /api/webhook/delete/[WebHookShortname]
Remove only one single url attached to the selected webHook.
A json body with the url parameter is required: { "url": "http://..." }
POST /api/webhook/trigger/[WebHookShortname]
Trigger a webHook. It requires a JSON body that will be turned over to the webHook URLs.
Out of the box, the iot-433mhz provides notifications through email and through a Telegram Bot. Of course you're free to develop your own notification system using our WebHooks API.
Notifications should be enabled and configured through the Menu > Settings
page. This is how the Settings page looks like:
By default there is a 5 second notification delay (editable from config.json:notificationDelay
). So you won't be flooded by alarms signals.
The Email notification system is under construction #18.
Soon will be available the official app on both the stores.
If you submit a pull request, thanks! There are a couple rules to follow though to make it manageable:
Inspired by pimatic-homeduino this is a project in his Beta stage. Documentation is under construction.