Home

Awesome

IoT 433Mhz Logo Build Status NPM Version Dependency Status <span class="badge-patreon"><a href="https://patreon.com/roccomuso" title="Donate to this project using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a></span>

  ___    _____     _  _  __________ __  __ _
 |_ _|__|_   _|   | || ||___ /___ /|  \/  | |__  ____
  | |/ _ \| |_____| || |_ |_ \ |_ \| |\/| | '_ \|_  /
  | | (_) | |_____|__   _|__) |__) | |  | | | | |/ /
 |___\___/|_|        |_||____/____/|_|  |_|_| |_/___|

Summary

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:

UI Demo

iot-433mhz UI

Features

Recommended Hardware

For more about the required 433mhz transmitter/receiver and the supported hardware see the hardware-layer page.

General Install

NPM

You can get it on npm:

npm install iot-433mhz -g

and then execute it from console with:

iot-433mhz

or Clone this Repo:

<code>git clone https://github.com/roccomuso/iot-433mhz.git</code>

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: <code>sudo chown -R $USER:$GROUP ~/.npm</code> combined with running <code>npm cache clean</code> to get any busted packages out of your cache. In addition, if the error still persist, try adding the flag <code>--unsafe-perm</code>:

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:

Browser Support

IEChromeFirefoxOperaSafari
IE 11+ ✔Latest ✔Latest ✔Latest ✔Latest ✔

Specific Setup

Iot-433Mhz is built on top of Node.js. The server is multi-platform, can run on different hardware combinations shown below:

A. Computer with Arduino connected and a 433 MHz transmitter and receiver.

tx rx arduino

Mac, Linux

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

Windows

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

B. Raspberry Pi (Raspbian Jessie) with 433 MHz transmitter and receiver

To use iot-433mhz on Raspberry Pi first do a system 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

Transmitter and Receiver connected to GPIO

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):

rpi 433mhz

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:

level shifter

here the voltage divider:

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.

Using RPi with an external Arduino.

The system can run on RPi using an external Arduino like the other platforms. To do that, just set to <code>true</code> the <code>use-external-arduino</code> option in the <code>config.json</code> file.

Heads Up! Sometimes the USB doesn't get detected on the fly (you should be able to see it with <code>ls /dev/tty*</code> - 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).

Config

Through the Settings page from the Web Interface, you can more or less change the general settings (stored in <code>config.json</code>). 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 <code>DEBUG=iot-433mhz:*</code>. You could also debug a specific part of the application providing as secondary param the file name, like <code>DEBUG=iot-433mhz:socketFunctions.js</code>.

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.

Usage

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

start iot-433mhz

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:

iot-433mhz cli options

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

Built-in Web Interface

Reachable on the <code>http://serverAddress:PORT</code>, the web <code>server_port</code> is defined in <code>config.json</code>, 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 <code>http://serverAddress:PORT/console.html</code>. (Thanks to console-mirroring).

Add to Homescreen

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.

Added to Homescreen

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.

What kind of devices the system works with

See the Hardware page.

API

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: <code>Authorization: Basic cm9vdDpyb290</code> where the last string is the base64 encoding of <code>root:root</code>, if you changed default username and password you should update the base64 text too (learn more on Basic Authentication Access).

Optional parameter: <code>card_img</code>, <code>background_color</code> (must be an hex color with). Json response: 200 OK - <code>{"done": true, "newCard": ...}</code> where newCard is the json card just inserted. Or <code>{"done": "false", "error": "error description..."}</code>

WebHooks

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.

Let's describe every event JSON payload you're gonna listen for according to the supplied <code>webHookShortname</code>:

<code>alarmTriggered = {"card_id": "...", "last_alert": 1453..., "code": ..., "shortname": "...", "room": "..." }</code> * NB. an alarmTriggered WebHook callback will be executed only if the alarm card is armed!

<code>newCard = {"card_id":"...", "headline": "", "shortname": "", "card_body": "", "img": "", "type": "switch/alarm/info", "room": "", "device": { *** }}</code> 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.

<code>cardDeleted = {"card_id": "..."}</code>

<code>newCode = {"code": "...", "bitlength": ..., "protocol": ...}</code> NB. The detected code could be ignored or already attached to a device card.

<code>switchToggle = {"card_id": "...", "is_on": true/false, "sent_code": ..., "timestamp": 1453... }</code>

Telegram Bot & Notifications

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 <code>Menu > Settings</code> page. This is how the Settings page looks like:

Telegram settings

By default there is a 5 second notification delay (editable from <code>config.json:notificationDelay</code>). So you won't be flooded by alarms signals.

The Email notification system is under construction #18.

Android & iOS Apps

Soon will be available the official app on both the stores.

Pull requests

If you submit a pull request, thanks! There are a couple rules to follow though to make it manageable:

Inspiration

Inspired by pimatic-homeduino this is a project in his Beta stage. Documentation is under construction.

Author

Rocco Musolino - @roccomuso