M2MLIGHT
USER GUIDE
Version 1.3
Date: Oct 15 2018
1. Introduction
2. Register User
3. IP cameras
4. Sensors
5. Actuators
6. Alerts
7. Subdomains
8. REST services and M2MData arduino library
9. Related links
10. Credits
This platform is aimed at enthusiasts who
have a basic knowledge of Internet of Thing (IoT) devices. M2mlight.com is
a free basic platform service for IoT devices. You can store your cameras,
sensors, actuators and alerts data in the cloud. Then, using your desktop
or smartphone via the Internet, you can see the videos, graphs, maps and
statistics of these devices.
Cameras, sensors and actuators can
receive and send data using a microcontroller like Arduino, Raspberry Pi
or Esp8266; and then, through a gateway or router can send this
information to the m2mlight platform in the cloud.
HTTP and RTSP protocols are used for
cameras; and, sensors, actuators and alarms use the HTTP and MQTT
protocols
2. REGISTER USER
In order to use this platform you need
to
register as a user using the option Login
and then
Register User.
- Email Address: required. Your
Email Address will be your user identifier in m2mlight.com. All messages
from cameras, sensors, actuators and alerts will be sent to this
address.
- Name: required. Your user
name.
- Password: required. Your
password of at least 7 characters
- Time Zone: required. Pick your
Time Zone. It is important to stored
your data with the appropriate
time.
- Domain: optional. The domain
of your home or small business. For example: caletagreen.com. This field
is not required but it is necessary if you want to use the subdomains
option.
- Town/City, Address and Phone: optional.
- Api_key: informative. This api_key is an unique identifier of
the user.
- Privacy Policy: required. You have to indicate that you agree to the Privacy
Policy of this website. You can read this policy in the indicated link.
If you want to change your account
information, including your password, you have to use the Account
option.
3. IP CAMERAS
An IP camera is a device connecting
directly to an Ethernet network.
The IP CAMERAS option allows you to manage your Ip cameras. You can add,
delete and edit a camera. It permits you to stop and start the motion
characteristic of a camera. Also, you can monitor and see camera videos.
With the second part of this
dialog, you can add or register a new camera. The maximum number of cameras
that you can register is 4.
A camera has the following required fields:
- Brand: you have to choose the
brand of your camera. The brands listed are those supported
by m2mlight at this moment.
- Model: the model of your
camera.
- Protocol: the stream protocol.
It can be http or rtsp.
- Environment: it can be Outdoor
or Indoor
- Name: the camera name. You
can not have two cameras with the same name.
- Ip or domain: the IP address
or the domain of the camera. It is the internal IP address or
sub-domain. The system checks
that it is a valid value.
- Port: the camera port number
- User name: the camera user
name
- Password: the camera password
In the first part of this dialog, you will
find the list of your cameras. Using the Edit
button you can update the camera properties. With the Delete
button you remove a camera and its motion registers; you need to confirm
this previously. The Stop
button allow to stop motion property and the Start
button allow to start motion property.
Api_key is the unique identifier of
the camera and you can not change this value.
The Status of a camera can
be:
Motion property is enable
Motion property is disable
Camera is disconnected for any reason
Daemons process check periodically each camera and set this status.
Using the Monitor button you
can see online the camera and its motions videos of the last month.
With the Live Cameras Panel
button, you can see all cameras on line.
4. SENSORS
A sensor is a device that detects changes
in the ambient conditions and transmits this information. For example,
there are sensors of temperature, light, humidity, motion, electric
current, power consumption, etc.
The SENSORS option allows you to manage
your sensors. You can add, delete and edit a sensor. With this option you
define sensors that have periodically values: singles values or location
values (longitude and latitude). In this platform, coordinates values
obtained from GPS devices are considered sensors.
For a sensor, you can upload data and see its status. For example, you can
see if the sensors values are out of range, according to defined min and
max limits.
Also, you can display and download stored data, and see graphs of these
data.
With the second part of this dialog, you can add or register a
new sensor. The maximum number of sensors you can register is 10.
A sensor has
the following fields:
- Name: required. The sensor
name. You can not have two sensors with the same name.
- Sensor type: you have two
alternatives, single value (default) or location values. If you choice
location values the measure field is always Degrees (longitude and
latitude).
- Measure:
required. A standard unit used to express the size, amount, or degree of
something. For example: Watts.
- Email-messages: you can choice
enable or disable. Enable, if you want to receive email messages when
the sensor is not registering values or the data are out of range.
Disable, if you do not receive email messages.
- Minimum value: optional. The
minimum value to be within a certain range.
- Maximum value: optional. The
maximum value to be within a certain range.
If you define minimum or maximum value,
after each insert of a new value the system checks if this value exceeded
the defined range and it informs you with an email.
In the first part of this dialog, you will
find the list of your sensors. Using the Edit
button you can update the sensor properties. With the Delete
button you remove a sensor and its register values; you need to confirm
this previously. The Stop button set the disable status
and the Start button set the
enable status.
The Status of a sensor can be:
- Sensor is enable and it is registering values
- Sensor is disable
- Sensor is not registering values
Sensor values are out of range
Daemons process check periodically each
sensor and set this status. If
a sensor has not registered
a value in the cloud in the last
10 minutes, the system changes its
state and sends a email message to
user if Email-messages property is enable.
For a sensor, the minimum interval between two
inserted values is 10 seconds.
Namely, if
you try to insert a value
in a range of less than 10
seconds, the value will not inserted.
Also,
for a sensor, the minimum interval between
two emails sent is 3,600 seconds (one hour).
Namely, if there are continuous news, you will receive a separate email
for at least one hour.
Api_key
is the unique identifier of the sensor and you can not change this value. You can add sensor values using this api_key and the Server functions or M2MData
library.
The Graphics button allow you to see line
graphs of these data, graphs by 5 minutes, an hour, a day,
a week or a month.
These
graphics work with most popular browsers:
Chrome and Firefox.
Using the Data
button you can display and download stored data.
In the case of location sensors, with the Map
button, you can see a Google Map with the location.
With the Live Sensor
Panel button, you can see all sensors values on line in one
screen. The
screen is refreshed every
5 seconds.
If you do not want to see a sensor in this screen you can change the
status to disable with the Stop button.
5. ACTUATORS
An actuator is a component that is responsible for controlling a mechanism
or system. For example, turning on/off lights, turning on/off an sound
alarm, opening or closing a door, etc.
The ACTUATORS option allows you to manage your actuators. You can add,
delete and edit a actuator.
With this option you can do a remote control (manual or automatic) of an
actuator.
Also, you can display and download registered actions of an actuator.
With the second part of this dialog, you can add or register a new
actuator.
An actuator has
the following fields:
- Name: required. The actuator
name. You can not have two actuators with the same name.
- Email messages: you can choice
enable or disable. Enable, if you want to receive email messages when an
action occurs. Disable, if you do not receive email messages.
- Automatic control: if you want to
have automatic remote control you have to choice the Enable option.
- Ip or domain: optional. Ip
address or domain of controller device. For example, the ip address of
an arduino with ethernet shield.
- Port: optional. The port of
controller device.
- Action: it can be ON or OFF. This
action name will be sent in the message to controller device.
- Start HH:MM: optional. The start
time (HH:MM) for the action. It is the time to be executed the action
daily.
- Week-day: enable or disable
for each day. Enable means that the action must be executed this day.
This property allows you to choice the days of the week when action will
be executed.
In the first part of this dialog, you will find the list of your actuators.
Using the Edit button you can
update the actuator properties. With the Delete
button you remove an actuator and its register values; you need to confirm
this previously. The Stop button
set the disable status and the Start button
set the enable status.
The Status of an actuator can be:
- Actuator is enable
- Actuator is disable
For an actuator,
the minimum interval between two emails sent due to an actuator
action is 10 seconds.
Api_key is the unique
identifier of the actuator and you can not change this value. You
can manage actuators using this
api_key and the Server functions or M2MData library.
The Do Now button execute immediately an actuator action at defined
start HH:MM. It sends a message (http call) to controller device. This
message is displayed on the screen and registered as an actuator manual
action.
For a sensor, the Data button allows to see the executed actuators
actions.
6. ALERTS
An
alert is a message sent by e-mail that gives you useful
information. You can define an alert when certain event occurs.
For example: sensors of motion and occupancy, proximity sensors, contact
sensors (open door or window), etc
The ALERTS option allows you to manage your alerts. You can add, delete
and edit an alert. Also, you can to display and download history stored
data.
With the second part of this dialog, you can add or
register a new alert.
An
alert has the following fields:
- Name: required.
The sensor name. You can not have two sensors with the same name.
- Message:
required. The message to be sent.
- E-mail
interval: interval between
messages in seconds (default is 3,600 seconds
that is equal to an hour). The minimum is 60 seconds.
In the first part of this dialog, you will
find the list of your alerts. Using the Edit
button you can update the alert properties. With the Delete
button you remove an alert and its register values; you need to confirm
this previously. The Stop button
allow to disable an alert and the Start
button allow to enable it. To send an e-mail the status must be
enable.
The Status of an alert can be:
- Alert is enable
- Alert is disable
Api_key is the unique
identifier of the alert and you can not change this value.
You can add alerts values using
this api_key and the Server
functions or M2MData library.
Using the Data button you can
display and download stored data alerts sent.
7. SUBDOMAINS
M2Mlight platform offers a
DNS (Domain Name Server) service if you have a domain name. You can use
this option if you need an internal DNS at your home.
First, register your domain name in your m2mlight account. Next register
here your subdomains and set in your main router the DNS equal to
pdns.caletagreen.com.
A subdomain is a domain that is a part of a main domain. For example, the
subdomain gardencontrol.caletegreen.com is part of the domain
caletagreen.com. It is useful when you need to give a name to an internal
IP address and then using this name internal o externally together with a
port.
This local DNS is not related to the others options of cameras, sensors,
alerts, etc. That
is, you can use this Subdomains option regardless of the other
options.
With the second part of this
dialog, you can add or register a new sub-domain.
First, you need to register a
domain using the Register User Dialog.
A sub-domain has the following fields:
- Name: the sub-domain name.
You can not have two sub-domains with the same name.
- Ip address: the internal Ip
address
In the first part of this dialog, you will
find the list of your sub-domains. Using the Edit
button you can update the sub-domains properties. With the Delete button you remove a sub-domain.
8. REST SERVICES AND M2MDATA
ARDUINO LIBRARY
REST services (server functions) and a M2M
Arduino library allow to use M2Mlight platform. First, you need to
register the sensor, actuator or alert and then obtain the api_key in
m2mlight.com.
You can find examples of this use in
https://github.com/m2mlight/m2mData and projects
located on www.caletagren.com.
These REST services and Arduino library can be used to send and receive
values between the m2mlight platform and a program in a microcontroller or
computer (arduino, raspberry, esp8266, etc.) or in a mobile device (tablet
or smartphone).
The communication with the m2mlight platform can be using Ethernet
(Arduino Ethernet or ENC28J60 shields) or GSM (SIM800L module).
You can download this library and see more information in:
https://github.com/m2mlight/m2mData
8.1. REST services
To upload/download data to m2mlight
platform using http from a browser or program, you can employ the
following REST services:
a) Sensors:
-> Name: send_sensor_value
Description: upload (save) a single sensor "value" of
a sensor identified by "api_key"
Call example: https://m2mlight.com/iot/send_sensor_value?api_key=250hhCIHeO&value=200
Return: 0 if a value is successfully inserted, -1 for
invalid api_key or disable status, -2 if the interval between two values is
less than 10 seconds.
-> Name: send_sensor_location
Description: upload (save) a location sensor "latitude" and
"longitude of a sensor identified by "api_key"
Call example:
https://m2mlight.com/iot/send_sensor_location?api_key=26hyCIHeO&latitude=-0.158382&longitude=-78.45534
Return: 0 if values are successfully inserted, -1 for invalid
api_key or disable status, -2 if the interval between two values is less
than 10 seconds.
-> Name: read_sensor_value
Description: return the last stored value of a single sensor
identified by "api_key"
Call example:
https://m2mlight.com/iot/read_sensor_value?api_key=300uhxXsAH
b) Actuators:
-> Name: send_email_action
Description: send an email related to an actuator action identified
by api_key. The minimum interval between two emails is 10 seconds.
Call example:
http://m2mlight.com/iot/send_email_action?api_key=LrkD1njci8
Return: 0 if the mailing is successful
-> Name: read_actuator_hour
Description: return the start hour (HH:MM) of an actuator identified
by "api_key"
Call example:
http://m2mlight.com/iot/read_actuator_hour?api_key=180SgN4pHk
-> Name: update_actuator_hour
Description: update the start hour "start_hour" of the actuator
identified by "api_key"
Call example:
http://m2mlight.com/iot/update_actuator_hour?api_key=a6ruhxX&start_hour=10:30
Return: -1 if HH:MM format is not correct
c) Alerts
-> Name: send_email_alert
Description: send an email related to an alert identified by api_key.
The minimum interval between two emails is the email_time_interval property
Call example:
http://m2mlight.com/iot/send_email_alert?api_key=6trkDnjci8
Return: 0 if the mailing is successful
You can use these functions inside an C++ code (Arduino or Esp8266) or
Python code (Raspberry). If you are using an Arduino is better to use the
M2MData library.
If you are using a GSM/GPRS chip like SIM800L then you can connect to
m2mlight.com directly with http commands. See example_use_sim800.ino.
8.2. M2MData Arduino library
The m2mData library is an Arduino library
that allows you to store and retrieve data of sensors, actuators and
alerts to/from m2mlight.
You can use the http or mqtt protocol.
You need to create a m2mData folder in your Arduino Libraries and download
the files: m2mData.h and m2mData.cpp
When
Arduino is connected to Internet, you have the following functions:
a) Sensors
// Store a single "value" of a sensor identified with "api_key" using
the http protocol
void sendValue(char api_key[], float value);
// Store a single "value" of a sensor identified with "api_key"
using the mqtt protocol
void sendValueMqtt(char api_key[], float value);
// Store coordinates values of a location sensor identified with
"api_key"
void sendCoordinates(char api_key[], float latitude, float
longitude);
// Return the last single value of a sensor identified with "api_key"
float readValue(char api_key[]);
b) Actuators
// Send an email about an action of an actuator identified with
"api_key"
void sendEmailAction(char api_key[]);
// Return the star hour (HH:MM) of an actuator identified with
"api_key"
String readActuatorHour(char api_key[]);
// Update the start hour "start_hour" (HH:MM) of an actuator
identified with "api_key"
void updateActuatorHour(char api_key[], char start_hour[]);
c) Alerts
// Send an email of an alert identified with "api_key"
void sendEmailAlert(char api_key[]);
9. RELATED LINKS
- https://github.com/m2mlight/m2mData
- http://caletagreen.com
- https://github.com/caletagreen/Automation
10. CREDITS
Some open source software, used in this platform, deserve special credit:
