MySensors

MySensors Documentation

Connect, right now, with #sensors you care about.

The Internet of Things (IoT) will enable objects to become active participants of everyday activities. With the introduction of low cost devices such as Android mobile phones and Raspberry-pi, Internet of Things (IoT) gets a little bit closer to life. IoT systems promises a lot but still lacks interoperability and privacy. Even the people living in the developing world can do innovative applications to solve their day to day problems if we can solve the interoperability and privacy issues.Therefore we developed a social network like platform called MySensors (www.mysensors.mobi) to share and control IoT. Developed new innovative Mysensors platform strengthens the protection of the user's privacy with its cryptographic protocol and new Senze language.MySensors open platform facilitates the communication in between devices and people. It opens wide variety of applications that can be implemented.


In the areas such as healthcare, social networks, safety, human rights, environmental monitoring, and transportation. So in general applications of MySenosrs help people in their everyday life. Since MySensors connects sensors you care about, people who have the sensors to monitor and control gets the benefits of it.

MySensors provides a tweet like interface called Senze to the application developers. By using this interface various applications can be integrated into MySenosors.
Author: SCoRe Lab
Contact: info@scorelab.org
Author URL: http://www.scorelab.org
Website URL: http://mysensors.mobi
Current Version: 1.1.0
Documentation Version 1.1.0
Created: 2014-06-01
Modified: 2014-06-03

Senze New sensing language which has its own syntax

Main component of the MySensors platform is the Senzes which are very similar to twitter messages. These Senzes can be used to build various applications and integrated into the existing systems. Senzes are capable of expressing any kind of sensing to the target devices.

Senze Syntax

Basically a Senze consists of three (3) components as follows:

1. Senze type Type of a Senze (SHARE, GET, DATA etc.)
2. Sensor names started with # tag and followed by a sensor name (#tmp, #lat, #lon etc.)
3. Target node started with @ sign and followed by the name (@user1, @device1 etc.)

Senze Types

At present five different Senze types are supported by MySensors platform. These types are PUT, LOGIN, GET, SHARE and DATA.

Senze Type Basic Functionality
PUT Requests an action on the device or the server
LOGIN Logs user/device to the system if given credentials are matched
GET Requests data or statistics from a specified device or the server
SHARE Shares a sensor to a particular online device or a user (node)
DATA Contains the response to the above Senzes with sensors values or operational status.

Opposite of a Senze

Inserting : (The Colon) in front of PUT, LOGIN, SHARE Senze types,

:PUT Reversed an action on the device or the server
:LOGIN Logs out user/device from the system
:SHARE Unshares a sensor from a particular online device or a user (node)

Syntax Basic Senze Syntax

Senze request : starts with Senze type followed by sensors and finally to which node (device or user) the Senze request goes to.

Senze response : starts with @node followed by Senze type and finally the sensors data or operational status.

A node can request a server to create an account by using PUT Senze as follows:
Senze PUT #name device1 #enckey ****** #phone ****** @mysensors
Meaning It creates a user account called device1 with the given security key and phone number at mysensor server.
As shown in the above Senze user sends PUT Senze to the MySensor server. The system creates a user account called device1 with the given security key and phone number if there's no conflicts.
Success response @mysensors DATA #name u1 #msg UserCreated
Failure response @mysensors DATA #name u1 #msg UserCreationFailed
After creating an account nodes can access the server by sending LOGIN Senze as follows:
Senze LOGIN #name u1 #enckey ********* @mysensors
Meaning Allows the user to login to the system if their credentials match.
As shown in the above Senze user u1 sends LOGIN Senze to the MySensor server. The system checks the username and password and allows the node(u1) to access the system.
Success response @mysensors DATA #msg LoginSuccess
Failure response @mysensors DATA #msg LoginFailed
Similarly each device needs to be registered with the MySensors server. Devices use public, private keys for the registration. node can request to create account by sending PUT Senze as follows :
Senze PUT #name device1 #signature *** #pubkey *** @mysensors
Meaning Allows the user to login to the system if their credentials match.
As shown in the above Senze device sends PUT Senze to the MySensor server. The system creates a user account called device1 with the given signature and public key if there's no conflicts.
Success response @mysensors DATA #name device1 #msg UserCreated
Failure response @mysensors DATA #name device1 #msg UserCreationFailed
Then the device can also login to the system by sending the following LOGIN Senze.
Senze LOGIN #name *** #signature *** @mysensors.
Meaning Allows the user to login to the system if their username and signature verified.
As shown in the above Senze node(device1) sends LOGIN Senze to the MySensor server. The system verifies the username and signature and allows the node(device1) to access the system.
Success response @mysensors DATA #msg LoginSuccess.
Failure response @mysensors DATA #msg LoginFailed.
After successful login, a device can share its sensors and actuators to online users and devices. In order to do this device has to send the SHARE Senze.
Senze SHARE #tmp @u1
Meaning A sender node (let’s say device1) would like to share a temperature values with the user called u1. The system sends the Senze to the server and to the specified node (eg: u1) saying that the temperature sensor is shared.
Shares its sensors and actuators to online users and devices.
Receiver(u1) gets @device1 SHARE #tmp
Sender(device1) gets @mysensors DATA #msg SharedDone
After the user or device receives sharing Senze, it can request the specified sensor data from a specified device by sending the following GET Senze.
Senze GET #tmp @device1
Meaning Sender node (let’s say u1) would like to receive temperature values from the device1.
Requests specified sensors and actuators data from online users or devices.
The specified device, for which the request is sent, gets the following Senze:
Receiver(device1) gets @u1 GET #tmp
If the request was successfully delivered the following Senze is received by the sender:
Sender(u1) gets @mysensors DATA #msg GetSendDone
If the Senze cannot deliver to the recipient, the sender gets the following Senze:
Sender(u1) gets @mysensors DATA #msg GetSendFailed
Upon receiving GET Senze device has to respond with DATA Senze. According to the example device1 sends the following DATA Senze to the u1.
Senze DATA #tmp xxxx @u1
Meaning Sender node (device1) sends it's temperature value to data requested user.
Receiver sends requested sensor data to the data requesting user or device.
The receiver (eg: u1) gets the values from the server as follows:
Receiver(u1) gets @device1 DATA #tmp xxxx
The PUT Senze sends an action request asking for the specified task from a specified device.
Senze PUT #switch1 @device1
Meaning Sender node (let’s say u1) would like to turn on the switch1 at the device1.
Sender sends request to a sensor or an actuator asking to perform an action.
The specified device, for which the request is sent, gets the following Senze:
Receiver(device1) gets @u1 PUT #switch1
If the action request was successfully delivered, the following Senze is received by the sender:
Sender(u1) gets @mysensors DATA #msg PutSendDone
If the Senze cannot deliver to the recipient, the sender gets the following Senze:
Sender(u1) gets @mysensors DATA #msg GetSendFailed
After receiving the PUT Senze, the device node performs the action and sends the following DATA Senze.
Senze DATA #switch1 ON @u1
Meaning Receiver node (device1) sends it's switch status to action requested user.
Receiver sends requested action status to the action requesting user or device.
The requesting node receives the action status from the device node (eg: device1)
Receiver(u1) gets @device1 DATA #switch1 ON
After sending the data Senze, the sender gets the following Senze:
Sender(device1) gets @mysensors DATA #msg DataSendDone

Conditional Senzes Do things with Intelligence.

The conditional Senze request allows the user to request data with a given condition.
Senze PUT #ac @device1 IF #tmp > some_value
Meaning The above is an example of a Senze that tells the dvice1 to turn on the air conditioner if temperature value exceeds a given value.
Response to the above Senze would be: @device1 DATA #ac ON
The following is an example of a Senze that requesting the status of the air conditioner if temperature values exceeds a given value.
Senze GET #ac @device1 IF #tmp > some_value
Meaning An example of a Senze that requesting the status of the air conditioner if temperature values exceeds a given value.
Response to the above Senze would be: @device1 DATA #ac OFF
The request can be sent for a given time period as well.
Senze GET #tmp @device1 FOR Ts
Meaning The above is an instance where the request is sent for the duration of T seconds. The following DATA Senze will receive every 1 second until T seconds have elapsed.
Response to the above Senze in each second: @device1 #tmp value

Similarly devices and users can generate differnt kinds of Senze to access the data and control the devices via MySensors.