README.md 55 KB
Newer Older
DV's avatar
DV committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
NodeManager is intended to take care on your behalf of all those common tasks a MySensors node has to accomplish, speeding up the development cycle of your projects.

NodeManager includes the following main components:

* Sleep manager: allows managing automatically the complexity behind battery-powered sensors spending most of their time sleeping
* Power manager: allows powering on your sensors only while the node is awake
* Battery manager: provides common functionalities to read and report the battery level
* Remote configuration: allows configuring remotely the node without the need to have physical access to it
* Built-in sensors: for the most common sensors, provide embedded code so to allow their configuration with a single line

## Features

* Manage all the aspects of a sleeping cycle by leveraging smart sleep
* Allow configuring the sleep mode and the sleep duration remotely
* Allow waking up a sleeping node remotely at the end of a sleeping cycle
* Allow powering on each connected sensor only while the node is awake to save battery
* Report battery level periodically and automatically
* Calculate battery level without requiring an additional pin and the resistors
* Report battery voltage through a built-in sensor
* Can report battery level on demand
* Allow rebooting the board remotely
* Provide out-of-the-box sensors personalities and automatically execute their main task at each cycle

24
## Installation
25
* Download the package or clone the git repository at https://github.com/mysensors/NodeManager
DV's avatar
DV committed
26
27
28
29
30
31
32
* Open the provided sketch template and save it under a different name
* Open `config.h` and customize both MySensors configuration and NodeManager global settings
* Register your sensors in the sketch file
* Upload the sketch to your arduino board

Please note NodeManager cannot be used as an arduino library since requires access to your MySensors configuration directives, hence its files have to be placed into the same directory of your sketch.

33
### Upgrade
34
35
36
37
* Download the package
* Replace the NodeManager.cpp and NodeManager.h of your project with those just downloaded
* Review the release notes in case there is any manual change required to the existing sketch or config.h file

38
## Configuration
DV's avatar
DV committed
39
40
NodeManager configuration includes compile-time configuration directives (which can be set in config.h), runtime global and per-sensor configuration settings (which can be set in your sketch) and settings that can be customized remotely (via a special child id).

41
### Setup MySensors
DV's avatar
DV committed
42
43
Since NodeManager has to communicate with the MySensors gateway on your behalf, it has to know how to do it. Place on top of the `config.h` file all the MySensors typical directives you are used to set on top of your sketch so both your sketch AND NodeManager will be able to share the same configuration. For example:
~~~c
44
45
46
47
/**********************************
 * Sketch configuration
 */

48
#define SKETCH_NAME "NodeManager"
49
50
51
52
53
54
55
#define SKETCH_VERSION "1.0"

/**********************************
 * MySensors node configuration
 */

// General settings
56
#define MY_BAUD_RATE 9600
DV's avatar
DV committed
57
//#define MY_DEBUG
58
//#define MY_NODE_ID 100
DV's avatar
DV committed
59

60
// NRF24 radio settings
DV's avatar
DV committed
61
62
63
#define MY_RADIO_NRF24
//#define MY_RF24_ENABLE_ENCRYPTION
//#define MY_RF24_CHANNEL 76
64
//#define MY_RF24_PA_LEVEL RF24_PA_HIGH
DV's avatar
DV committed
65

66
// RFM69 radio settings
DV's avatar
DV committed
67
68
69
//#define MY_RADIO_RFM69
//#define MY_RFM69_FREQUENCY RF69_868MHZ
//#define MY_IS_RFM69HW
70
//#define MY_RFM69_NEW_DRIVER
DV's avatar
DV committed
71
72
//#define MY_RFM69_ENABLE_ENCRYPTION
//#define MY_RFM69_NETWORKID 100
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
//#define MY_RF69_IRQ_PIN D1
//#define MY_RF69_IRQ_NUM MY_RF69_IRQ_PIN
//#define MY_RF69_SPI_CS D2

/**********************************
 * MySensors gateway configuration
 */
// Common gateway settings
//#define MY_REPEATER_FEATURE

// Serial gateway settings
//#define MY_GATEWAY_SERIAL

// Ethernet gateway settings
//#define MY_GATEWAY_W5100

// ESP8266 gateway settings
//#define MY_GATEWAY_ESP8266
//#define MY_ESP8266_SSID "MySSID"
//#define MY_ESP8266_PASSWORD "MyVerySecretPassword"

// Gateway networking settings
//#define MY_IP_ADDRESS 192,168,178,87
//#define MY_IP_GATEWAY_ADDRESS 192,168,178,1
//#define MY_IP_SUBNET_ADDRESS 255,255,255,0
//#define MY_PORT 5003
//#define MY_GATEWAY_MAX_CLIENTS 2
//#define MY_USE_UDP

// Gateway MQTT settings
//#define MY_GATEWAY_MQTT_CLIENT
//#define MY_CONTROLLER_IP_ADDRESS 192, 168, 178, 68
//#define MY_PORT 1883
//#define MY_MQTT_USER "username"
//#define MY_MQTT_PASSWORD "password"
//#define MY_MQTT_CLIENT_ID "mysensors-1"
//#define MY_MQTT_PUBLISH_TOPIC_PREFIX "mygateway1-out"
//#define MY_MQTT_SUBSCRIBE_TOPIC_PREFIX "mygateway1-in"

// Gateway inclusion mode
//#define MY_INCLUSION_MODE_FEATURE
//#define MY_INCLUSION_BUTTON_FEATURE
//#define MY_INCLUSION_MODE_DURATION 60
//#define MY_DEFAULT_LED_BLINK_PERIOD 300

// Gateway Leds settings
//#define MY_DEFAULT_ERR_LED_PIN 4
//#define MY_DEFAULT_RX_LED_PIN  5
//#define MY_DEFAULT_TX_LED_PIN  6
DV's avatar
DV committed
122
~~~
DV's avatar
DV committed
123

124
### Enable/Disable NodeManager's modules
DV's avatar
DV committed
125
126
127
128

Those NodeManager's directives in the `config.h` file control which module/library/functionality will be made available to your sketch. Enable (e.g. set to 1) only what you need to ensure enough space is left to your custom code.

~~~c
129
130
131
// if enabled, enable debug messages on serial port
#define DEBUG 1

DV's avatar
DV committed
132
133
134
135
136
137
138
139
140
// if enabled, enable the capability to power on sensors with the arduino's pins to save battery while sleeping
#define POWER_MANAGER 1
// if enabled, will load the battery manager library to allow the battery level to be reported automatically or on demand
#define BATTERY_MANAGER 1
// if enabled, allow modifying the configuration remotely by interacting with the configuration child id
#define REMOTE_CONFIGURATION 1
// if enabled, persist the configuration settings on EEPROM
#define PERSIST 0

user2684's avatar
user2684 committed
141
// if enabled, send a SLEEPING and AWAKE service messages just before entering and just after leaving a sleep cycle and STARTED when starting/rebooting
142
#define SERVICE_MESSAGES 0
DV's avatar
DV committed
143
144
145
// if enabled, a battery sensor will be created at BATTERY_CHILD_ID and will report vcc voltage together with the battery level percentage
#define BATTERY_SENSOR 1

146
// Enable this module to use one of the following sensors: SENSOR_ANALOG_INPUT, SENSOR_LDR, SENSOR_THERMISTOR, SENSOR_ML8511, SENSOR_ACS712, SENSOR_RAIN_GAUGE, SENSOR_RAIN, SENSOR_SOIL_MOISTURE
DV's avatar
DV committed
147
148
149
150
151
152
153
154
155
156
157
158
159
#define MODULE_ANALOG_INPUT 1
// Enable this module to use one of the following sensors: SENSOR_DIGITAL_INPUT
#define MODULE_DIGITAL_INPUT 1
// Enable this module to use one of the following sensors: SENSOR_DIGITAL_OUTPUT, SENSOR_RELAY, SENSOR_LATCHING_RELAY
#define MODULE_DIGITAL_OUTPUT 1
// Enable this module to use one of the following sensors: SENSOR_SHT21
#define MODULE_SHT21 0
// Enable this module to use one of the following sensors: SENSOR_DHT11, SENSOR_DHT22
#define MODULE_DHT 0
// Enable this module to use one of the following sensors: SENSOR_SWITCH, SENSOR_DOOR, SENSOR_MOTION
#define MODULE_SWITCH 0
// Enable this module to use one of the following sensors: SENSOR_DS18B20
#define MODULE_DS18B20 0
DV's avatar
DV committed
160
161
162
163
// Enable this module to use one of the following sensors: SENSOR_BH1750
#define MODULE_BH1750 0
// Enable this module to use one of the following sensors: SENSOR_MLX90614
#define MODULE_MLX90614 0
user2684's avatar
user2684 committed
164
165
// Enable this module to use one of the following sensors: SENSOR_BME280
#define MODULE_BME280 0
166
167
168
169
170
171
// Enable this module to use one of the following sensors: SENSOR_SONOFF
#define MODULE_SONOFF 0
// Enable this module to use one of the following sensors: SENSOR_BMP085
#define MODULE_BMP085 0
// Enable this module to use one of the following sensors: SENSOR_HCSR04
#define MODULE_HCSR04 0
172
173
// Enable this module to use one of the following sensors: SENSOR_MCP9808
#define MODULE_MCP9808 0
174
175
// Enable this module to use one of the following sensors: SENSOR_MQ
#define MODULE_MQ 0
DV's avatar
DV committed
176
177
~~~

178
### Installing the dependencies
DV's avatar
DV committed
179
180
181
182
183
184
185
186
187
188

Some of the modules above rely on third party libraries. Those libraries are not included within NodeManager and have to be installed from the Arduino IDE Library Manager (Sketch -> Include Library -> Manager Libraries). You need to install the library ONLY if the module is enabled:

Module  | Required Library
 ------------- | -------------
MODULE_SHT21 | https://github.com/SodaqMoja/Sodaq_SHT2x
MODULE_DHT | https://github.com/adafruit/DHT-sensor-library
MODULE_DS18B20 | https://github.com/milesburton/Arduino-Temperature-Control-Library
MODULE_BH1750 | https://github.com/claws/BH1750
MODULE_MLX90614 | https://github.com/adafruit/Adafruit-MLX90614-Library
user2684's avatar
user2684 committed
189
MODULE_BME280 | https://github.com/adafruit/Adafruit_BME280_Library
190
191
192
MODULE_SONOFF | https://github.com/thomasfredericks/Bounce2
MODULE_BMP085 | https://github.com/adafruit/Adafruit-BMP085-Library
MODULE_HCSR04 | https://github.com/mysensors/MySensorsArduinoExamples/tree/master/libraries/NewPing
193
MODULE_MCP9808 | https://github.com/adafruit/Adafruit_MCP9808_Library
DV's avatar
DV committed
194

195
### Configure NodeManager
DV's avatar
DV committed
196
197
198
199

Node Manager comes with a reasonable default configuration. If you want/need to change its settings, this can be done in your sketch, inside the `before()` function and just before registering your sensors. The following methods are exposed for your convenience:

~~~c
200
    // [10] send the same service message multiple times (default: 1)
DV's avatar
DV committed
201
    void setRetries(int value);
202
    int getRetries();
DV's avatar
DV committed
203
    #if BATTERY_MANAGER == 1
204
      // [11] the expected vcc when the batter is fully discharged, used to calculate the percentage (default: 2.7)
DV's avatar
DV committed
205
      void setBatteryMin(float value);
206
      // [12] the expected vcc when the batter is fully charged, used to calculate the percentage (default: 3.3)
DV's avatar
DV committed
207
      void setBatteryMax(float value);
208
      // [13] after how many sleeping cycles report the battery level to the controller. When reset the battery is always reported (default: -)
DV's avatar
DV committed
209
      void setBatteryReportCycles(int value);
210
      // [14] after how many minutes report the battery level to the controller. When reset the battery is always reported (default: 60)
211
      void setBatteryReportMinutes(int value);
212
      // [15] if true, the battery level will be evaluated by measuring the internal vcc without the need to connect any pin, if false the voltage divider methon will be used (default: true)
213
      void setBatteryInternalVcc(bool value);
214
      // [16] if setBatteryInternalVcc() is set to false, the analog pin to which the battery's vcc is attached (https://www.mysensors.org/build/battery) (default: -1)
215
      void setBatteryPin(int value);
216
      // [17] if setBatteryInternalVcc() is set to false, the volts per bit ratio used to calculate the battery voltage (default: 0.003363075)
217
      void setBatteryVoltsPerBit(float value);
218
      // [18] If true, wake up by an interrupt counts as a valid cycle for battery reports otherwise only uninterrupted sleep cycles would contribute (default: true)
219
      void setBatteryReportWithInterrupt(bool value);
220
221
      // [2] Send a battery level report to the controller
      void batteryReport();
DV's avatar
DV committed
222
    #endif
223
    // [3] define the way the node should behave. It can be (0) IDLE (stay awake withtout executing each sensors' loop), (1) SLEEP (go to sleep for the configured interval), (2) WAIT (wait for the configured interval), (3) ALWAYS_ON (stay awake and execute each sensors' loop)
224
225
    void setSleepMode(int value);
    void setMode(int value);
226
227
    int getMode();
    // [4] define for how long the board will sleep (default: 0)
228
    void setSleepTime(int value);
229
230
    int getSleepTime();
    // [5] define the unit of SLEEP_TIME. It can be SECONDS, MINUTES, HOURS or DAYS (default: MINUTES)
231
    void setSleepUnit(int value);
232
    int getSleepUnit();
233
234
    // configure the node's behavior, parameters are mode, time and unit
    void setSleep(int value1, int value2, int value3);
235
    // [19] if enabled, when waking up from the interrupt, the board stops sleeping. Disable it when attaching e.g. a motion sensor (default: true)
236
    void setSleepInterruptPin(int value);
DV's avatar
DV committed
237
238
    // configure the interrupt pin and mode. Mode can be CHANGE, RISING, FALLING (default: MODE_NOT_DEFINED)
    void setInterrupt(int pin, int mode, int pull = -1);
239
    // [20] optionally sleep interval in milliseconds before sending each message to the radio network (default: 0)
DV's avatar
DV committed
240
    void setSleepBetweenSend(int value);
241
    int getSleepBetweenSend();
DV's avatar
DV committed
242
243
244
245
    // register a built-in sensor
    int registerSensor(int sensor_type, int pin = -1, int child_id = -1);
    // register a custom sensor
    int registerSensor(Sensor* sensor);
246
247
    // [26] un-register a sensor
    void unRegisterSensor(int sensor_index);
DV's avatar
DV committed
248
249
    // return a sensor by its index
    Sensor* get(int sensor_index);
250
251
    Sensor* getSensor(int sensor_index);
    // assign a different child id to a sensor
user2684's avatar
user2684 committed
252
    bool renameSensor(int old_child_id, int new_child_id);
DV's avatar
DV committed
253
254
    #if POWER_MANAGER == 1
      // to save battery the sensor can be optionally connected to two pins which will act as vcc and ground and activated on demand
255
256
      void setPowerPins(int ground_pin, int vcc_pin, int wait_time = 50);
      // [23] if enabled the pins will be automatically powered on while awake and off during sleeping (default: true)
DV's avatar
DV committed
257
      void setAutoPowerPins(bool value);
258
      // [24] manually turn the power on
DV's avatar
DV committed
259
      void powerOn();
260
      // [25] manually turn the power off
261
      void powerOff(); 
DV's avatar
DV committed
262
    #endif
263
    // [21] set this to true if you want destination node to send ack back to this node (default: false)
user2684's avatar
user2684 committed
264
    void setAck(bool value);
265
    bool getAck();
266
267
    // request and return the current timestamp from the controller
    long getTimestamp();
268
269
    // Request the controller's configuration on startup (default: true)
    void setGetControllerConfig(bool value);
270
    // [22] Manually set isMetric setting
271
272
273
274
    void setIsMetric(bool value);
    bool getIsMetric();
    // Convert a temperature from celsius to fahrenheit depending on how isMetric is set
    float celsiusToFahrenheit(float temperature);
275
276
    // return true if sleep or wait is configured and hence this is a sleeping node
    bool isSleepingNode();
277
278
279
280
281
282
283
284
285
286
287
    // [1] Send a hello message back to the controller
    void hello();
    // [6] reboot the board
    void reboot();
    // [8] send NodeManager's the version back to the controller
    void version();
    // [7] clear the EEPROM
    void clearEeprom();
    // [9] wake up the board
    void wakeup();
    // process a remote request
288
    void process(Request & request);
289
290
    // return the value stored at the requested index from the EEPROM
    int loadFromMemory(int index);
291
    // [27] save the given index of the EEPROM the provided value
292
    void saveToMemory(int index, int value);
293
294
    // return vcc in V
    float getVcc();
DV's avatar
DV committed
295
296
297
298
299
~~~

For example

~~~c
user2684's avatar
user2684 committed
300
	nodeManager.setBatteryMin(1.8);
DV's avatar
DV committed
301
302
~~~

303
### Register your sensors
DV's avatar
DV committed
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
In your sketch, inside the `before()` function and just before calling `nodeManager.before()`, you can register your sensors against NodeManager. The following built-in sensor types are available:

Sensor type  | Description
 ------------- | -------------
SENSOR_ANALOG_INPUT | Generic analog sensor, return a pin's analog value or its percentage
SENSOR_LDR | LDR sensor, return the light level of an attached light resistor in percentage
SENSOR_THERMISTOR | Thermistor sensor, return the temperature based on the attached thermistor
SENSOR_DIGITAL_INPUT |  Generic digital sensor, return a pin's digital value
SENSOR_DIGITAL_OUTPUT | Generic digital output sensor, allows setting the digital output of a pin to the requested value
SENSOR_RELAY | Relay sensor, allows activating the relay
SENSOR_LATCHING_RELAY| Latching Relay sensor, allows activating the relay with a pulse
SENSOR_DHT11 | DHT11 sensor, return temperature/humidity based on the attached DHT sensor
SENSOR_DHT22 | DHT22 sensor, return temperature/humidity based on the attached DHT sensor
SENSOR_SHT21 | SHT21 sensor, return temperature/humidity based on the attached SHT21 sensor
SENSOR_SWITCH | Generic switch, wake up the board when a pin changes status
SENSOR_DOOR | Door sensor, wake up the board and report when an attached magnetic sensor has been opened/closed
SENSOR_MOTION | Motion sensor, wake up the board and report when an attached PIR has triggered
SENSOR_DS18B20 | DS18B20 sensor, return the temperature based on the attached sensor
DV's avatar
DV committed
322
323
324
SENSOR_HTU21D | HTU21D sensor, return temperature/humidity based on the attached HTU21D sensor
SENSOR_BH1750 | BH1750 sensor, return light level in lux
SENSOR_MLX90614 | MLX90614 contactless temperature sensor, return ambient and object temperature
user2684's avatar
user2684 committed
325
SENSOR_BME280 | BME280 sensor, return temperature/humidity/pressure based on the attached BME280 sensor
user2684's avatar
user2684 committed
326
SENSOR_MQ | MQ sensor, return ppm of the target gas
327
SENSOR_ML8511 | ML8511 sensor, return UV intensity
328
329
330
331
SENSOR_SONOFF | Sonoff wireless smart switch
SENSOR_BMP085 | BMP085/BMP180 sensor, return temperature and pressure
SENSOR_HCSR04 | HC-SR04 sensor, return the distance between the sensor and an object
SENSOR_ACS712 | ACS712 sensor, measure the current going through the attached module
332
SENSOR_MCP9808 | MCP9808 sensor, measure the temperature through the attached module
333
SENSOR_RAIN_GAUGE | Rain gauge sensor
334
335
SENSOR_RAIN | Rain sensor, return the percentage of rain from an attached analog sensor
SENSOR_SOIL_MOISTURE | Soil moisture sensor, return the percentage of moisture from an attached analog sensor
DV's avatar
DV committed
336
337
338

To register a sensor simply call the NodeManager instance with the sensory type and the pin the sensor is conncted to. For example:
~~~c
user2684's avatar
user2684 committed
339
340
	nodeManager.registerSensor(SENSOR_THERMISTOR,A2);
	nodeManager.registerSensor(SENSOR_DOOR,3);
DV's avatar
DV committed
341
342
~~~

user2684's avatar
user2684 committed
343
Once registered, your job is done. NodeManager will assign a child id automatically, present each sensor for you to the controller, query each sensor and report the value back to the gateway/controller at at the end of each sleep cycle. An optional child id can be provided as a third argument if you want to assign it manually. For actuators (e.g. relays) those can be triggered by sending a `REQ` message to their assigned child id.
DV's avatar
DV committed
344
345
346

When called, registerSensor returns the child_id of the sensor so you will be able to retrieve it later if needed. If you want to set a child_id manually, this can be passed as third argument to the function.

347
#### Creating a custom sensor
DV's avatar
DV committed
348

349
If you want to create a custom sensor and register it with NodeManager so it can take care of all the common tasks, you can create an inline class inheriting from `Sensor` or other subclasses and implement the following methods:
DV's avatar
DV committed
350
351
352
~~~c
    // define what to do during before() to setup the sensor
    void onBefore();
user2684's avatar
user2684 committed
353
354
	// define what to do during setup() by executing the sensor's main task
    void onSetup();
DV's avatar
DV committed
355
356
357
358
    // define what to do during loop() by executing the sensor's main task
    void onLoop();
    // define what to do during receive() when the sensor receives a message
    void onReceive(const MyMessage & message);
359
360
	// define what to do when receiving a remote configuration message
	void onProcess(Request & request);
DV's avatar
DV committed
361
362
363
364
~~~

You can then instantiate your newly created class and register with NodeManager:
~~~c
365
	nodeManager.registerSensor(new SensorCustom(&nodeManager,child_id, pin));
DV's avatar
DV committed
366
367
~~~

368
### Configuring the sensors
DV's avatar
DV committed
369
370
Each built-in sensor class comes with reasonable default settings. In case you want/need to customize any of those settings, after having registered the sensor, you can retrieve it back and call set functions common to all the sensors or specific for a given class.

user2684's avatar
user2684 committed
371
To do so, use `nodeManager.getSensor(child_id)` which will return a pointer to the sensor. Remeber to cast it to the right class before calling their functions. For example:
DV's avatar
DV committed
372
373

~~~c
user2684's avatar
user2684 committed
374
	((SensorLatchingRelay*)nodeManager.getSensor(2))->setPulseWidth(50);
DV's avatar
DV committed
375
376
377
~~~


378
#### Sensor's general configuration
DV's avatar
DV committed
379
380
381

The following methods are available for all the sensors:
~~~c
382
    // [1] where the sensor is attached to (default: not set)
DV's avatar
DV committed
383
    void setPin(int value);
384
385
    int getPin();
    // [2] child_id of this sensor (default: not set)
DV's avatar
DV committed
386
    void setChildId(int value);
387
    int getChildId();
DV's avatar
DV committed
388
389
    // presentation of this sensor (default: S_CUSTOM)
    void setPresentation(int value);
390
391
    int getPresentation();
    // [3] type of this sensor (default: V_CUSTOM)
DV's avatar
DV committed
392
    void setType(int value);
393
394
    int getType();
    // [4] description of the sensor (default: '')
user2684's avatar
user2684 committed
395
    void setDescription(char *value);
396
    // [5] For some sensors, the measurement can be queried multiple times and an average is returned (default: 1)
DV's avatar
DV committed
397
    void setSamples(int value);
398
    // [6] If more then one sample has to be taken, set the interval in milliseconds between measurements (default: 0)
DV's avatar
DV committed
399
    void setSamplesInterval(int value);
400
    // [7] if true will report the measure only if different than the previous one (default: false)
401
    void setTrackLastValue(bool value);
402
    // [8] if track last value is enabled, force to send an update after the configured number of cycles (default: -1)
DV's avatar
DV committed
403
    void setForceUpdate(int value);
404
    void setForceUpdateCycles(int value);
405
    // [9] if track last value is enabled, force to send an update after the configured number of minutes (default: -1)
406
    void setForceUpdateMinutes(int value);
407
    // [10] the value type of this sensor (default: TYPE_INTEGER)
DV's avatar
DV committed
408
    void setValueType(int value);
409
410
411
    int getValueType();
    // [11] for float values, set the float precision (default: 2)
    void  setFloatPrecision(int value);
DV's avatar
DV committed
412
413
    #if POWER_MANAGER == 1
      // to save battery the sensor can be optionally connected to two pins which will act as vcc and ground and activated on demand
414
415
      void setPowerPins(int ground_pin, int vcc_pin, int wait_time = 50);
      // [12] if enabled the pins will be automatically powered on while awake and off during sleeping (default: true)
DV's avatar
DV committed
416
      void setAutoPowerPins(bool value);
417
      // [13] manually turn the power on
DV's avatar
DV committed
418
      void powerOn();
419
      // [14] manually turn the power off
DV's avatar
DV committed
420
421
      void powerOff();
    #endif
user2684's avatar
user2684 committed
422
    // get the latest recorded value from the sensor
423
424
425
    int getValueInt();
    float getValueFloat();
    char* getValueString();
426
    // [15] After how many cycles the sensor will report back its measure (default: 1 cycle)
427
    void setReportIntervalCycles(int value);
428
    // [16] After how many minutes the sensor will report back its measure (default: 1 cycle)
429
    void setReportIntervalMinutes(int value);
430
431
    // process a remote request
    void process(Request & request);
432
433
    // return the pin the interrupt is attached to
    int getInterruptPin();
DV's avatar
DV committed
434
435
~~~

436
#### Sensor's specific configuration
DV's avatar
DV committed
437
438
439

Each sensor class can expose additional methods.

440
* SensorAnalogInput / SensorLDR / SensorRain / SensorSoilMoisture
DV's avatar
DV committed
441
~~~c
442
    // [101] the analog reference to use (default: not set, can be either INTERNAL or DEFAULT)
DV's avatar
DV committed
443
    void setReference(int value);
444
    // [102] reverse the value or the percentage (e.g. 70% -> 30%) (default: false)
DV's avatar
DV committed
445
    void setReverse(bool value);
446
    // [103] when true returns the value as a percentage (default: true)
DV's avatar
DV committed
447
    void setOutputPercentage(bool value);
448
    // [104] minimum value for calculating the percentage (default: 0)
DV's avatar
DV committed
449
    void setRangeMin(int value);
450
    // [105] maximum value for calculating the percentage (default: 1024)
DV's avatar
DV committed
451
452
453
    void setRangeMax(int value);
~~~

454
* SensorThermistor
DV's avatar
DV committed
455
~~~c
456
    // [101] resistance at 25 degrees C (default: 10000)
457
    void setNominalResistor(long value);
458
    // [102] temperature for nominal resistance (default: 25)
DV's avatar
DV committed
459
    void setNominalTemperature(int value);
460
    // [103] The beta coefficient of the thermistor (default: 3950)
DV's avatar
DV committed
461
    void setBCoefficient(int value);
462
    // [104] the value of the resistor in series with the thermistor (default: 10000)
463
    void setSeriesResistor(long value);
464
    // [105] set a temperature offset
DV's avatar
DV committed
465
466
467
    void setOffset(float value);
~~~

468
* SensorMQ
user2684's avatar
user2684 committed
469
~~~c
470
    // [101] define the target gas whose ppm has to be returned. 0: LPG, 1: CO, 2: Smoke (default: 1);
user2684's avatar
user2684 committed
471
    void setTargetGas(int value);
472
    // [102] define the load resistance on the board, in kilo ohms (default: 1);
user2684's avatar
user2684 committed
473
    void setRlValue(float value);
474
    // [103] define the Ro resistance on the board (default: 10000);
user2684's avatar
user2684 committed
475
    void setRoValue(float value);
476
    // [104] Sensor resistance in clean air (default: 9.83);
user2684's avatar
user2684 committed
477
    void setCleanAirFactor(float value);
478
    // [105] define how many samples you are going to take in the calibration phase (default: 50);
user2684's avatar
user2684 committed
479
    void setCalibrationSampleTimes(int value);
480
    // [106] define the time interal(in milisecond) between each samples in the cablibration phase (default: 500);
user2684's avatar
user2684 committed
481
    void setCalibrationSampleInterval(int value);
482
    // [107] define how many samples you are going to take in normal operation (default: 50);
user2684's avatar
user2684 committed
483
    void setReadSampleTimes(int value);
484
    // [108] define the time interal(in milisecond) between each samples in the normal operations (default: 5);
user2684's avatar
user2684 committed
485
486
487
488
489
490
491
492
493
    void setReadSampleInterval(int value);
    // set the LPGCurve array (default: {2.3,0.21,-0.47})
    void setLPGCurve(float *value);
    // set the COCurve array (default: {2.3,0.72,-0.34})
    void setCOCurve(float *value);
    // set the SmokeCurve array (default: {2.3,0.53,-0.44})
    void setSmokeCurve(float *value);
~~~

494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
* SensorACS712
~~~c
    // [101] set how many mV are equivalent to 1 Amp. The value depends on the module (100 for 20A Module, 66 for 30A Module) (default: 185);
    void setmVPerAmp(int value);
    // [102] set ACS offset (default: 2500);
    void setOffset(int value);
~~~

* SensorRainGauge
~~~c
    // [101] set how frequently to report back to the controller in minutes. After reporting the measure is resetted (default: 60)
    void setReportInterval(int value);
    // [102] set how many mm of rain to count for each tip (default: 0.11)
    void setSingleTip(float value);
~~~

510
* SensorDigitalOutput / SensorRelay
DV's avatar
DV committed
511
~~~c
512
    // [103] define which value to set to the output when set to on (default: HIGH)
513
    void setOnValue(int value);
514
    // [104] when legacy mode is enabled expect a REQ message to trigger, otherwise the default SET (default: false)
515
    void setLegacyMode(bool value);
516
    // [105] automatically turn the output off after the given number of minutes
517
    void setSafeguard(int value);
518
    // [106] if true the input value becomes a duration in minutes after which the output will be automatically turned off (default: false)
519
    void setInputIsElapsed(bool value);
520
521
    // [107] optionally wait for the given number of milliseconds after changing the status (default: 0)
    void setWaitAfterSet(int value);
522
    // manually switch the output to the provided value
523
    void setStatus(int value);
524
    // get the current state
525
526
527
528
529
530
531
532
533
534
535
    int getStatus();
~~~

* SensorLatchingRelay (in addition to those available for SensorDigitalOutput / SensorRelay)
~~~c
    // [201] set the duration of the pulse to send in ms to activate the relay (default: 50)
    void setPulseWidth(int value);
    // [202] set the pin which turns the relay off (default: the pin provided while registering the sensor)
    void setPinOff(int value);
    // [203] set the pin which turns the relay on (default: the pin provided while registering the sensor + 1)
    void setPinOn(int value);
DV's avatar
DV committed
536
537
~~~

538
*  SensorSwitch / SensorDoor / SensorMotion
DV's avatar
DV committed
539
~~~c
540
    // [101] set the interrupt mode. Can be CHANGE, RISING, FALLING (default: CHANGE)
DV's avatar
DV committed
541
    void setMode(int value);
542
    // [102] milliseconds to wait before reading the input (default: 0)
DV's avatar
DV committed
543
    void setDebounce(int value);
544
    // [103] time to wait in milliseconds after a change is detected to allow the signal to be restored to its normal value (default: 0)
DV's avatar
DV committed
545
    void setTriggerTime(int value);
546
    // [104] Set initial value on the interrupt pin (default: HIGH)
547
    void setInitial(int value);
DV's avatar
DV committed
548
549
~~~

550
*  SensorDs18b20
user2684's avatar
user2684 committed
551
552
553
~~~c
    // returns the sensor's resolution in bits
    int getResolution();
554
    // [101] set the sensor's resolution in bits
user2684's avatar
user2684 committed
555
    void setResolution(int value);
556
    // [102] sleep while DS18B20 calculates temperature (default: false)
557
    void setSleepDuringConversion(bool value);
558
559
    // return the sensors' device address
    DeviceAddress* getDeviceAddress();
user2684's avatar
user2684 committed
560
561
~~~

562
*  SensorBME280 / SensorBMP085
563
~~~c
564
    // [101] define how many pressure samples to keep track of for calculating the forecast (default: 5)
565
566
567
    void setForecastSamplesCount(int value);
~~~

568
* SensorHCSR04
569
~~~c
570
    // [101] Arduino pin tied to trigger pin on the ultrasonic sensor (default: the pin set while registering the sensor)
571
    void setTriggerPin(int value);
572
    // [102] Arduino pin tied to echo pin on the ultrasonic sensor (default: the pin set while registering the sensor)
573
    void setEchoPin(int value);
574
    // [103] Maximum distance we want to ping for (in centimeters) (default: 300)
575
576
577
    void setMaxDistance(int value);
~~~

578
*  SensorSonoff
579
~~~c
580
581
582
583
584
585
    // [101] set the button's pin (default: 0)
    void setButtonPin(int value);
    // [102] set the relay's pin (default: 12)
    void setRelayPin(int value);
    // [103] set the led's pin (default: 13)
    void setLedPin(int value);
586
587
~~~

588
### Upload your sketch
DV's avatar
DV committed
589
590
591
592
593
594

Upload your sketch to your arduino board as you are used to.

Check your gateway's logs to ensure the node is working as expected. You should see the node presenting itself, reporting battery level, presenting all the registered sensors and the configuration child id service.
When `DEBUG` is enabled, detailed information is available through the serial port. Remember to disable debug once the tests have been completed.

595
### Communicate with NodeManager and its sensors
DV's avatar
DV committed
596

597
You can interact with each registered sensor by asking to execute their main tasks by sending to the child id a `REQ` command (or a `SET` for output sensors like relays). For example to request the temperature to node_id 254 and child_id 1:
DV's avatar
DV committed
598
599
600
601
602

`254;1;2;0;0;`

To activate a relay connected to the same node, child_id 100:

603
`254;100;1;0;2;1`
DV's avatar
DV committed
604
605

No need to implement anything on your side since for built-in sensor types this is handled automatically. 
606
Once the node will be sleeping, it will report automatically each measure at the end of every sleep cycle, unless configured otherwise.
607

608
609
610
611
612
613
614
615
616
617
NodeManager exposes also a configuration service by default on child_id 200 so you can interact with it by sending `V_CUSTOM` type of messages and commands within the payload. For each `REQ` message, the node will respond with a `SET` message if successful. 
Almost all the functions made available through the API can be called remotely. To do so, the payload must be in the format `<function_id>[,<value_to_set>]` where function_id is the number between square brackets you can find in the description just above each function and, if the function takes and argument, this can be passed along in value_to_set. 
For example, to request a battery report, find the function you need to call remotely within the documentation:
~~~c
    // [2] Send a battery level report to the controller
    void batteryReport();
~~~
In this case the function_id will be 2. To request a battery report to the node_id 100, send the following message:
`<node_id>;<configuration_child_id>;<req>;0;<V_CUSTOM>;<function_id>`
`100;200;2;0;48;2`
618

619
620
621
622
623
624
625
The change the sleep time from e.g. 10 minutes as set in the sketch to 5 minutes:
~~~c
    // [4] define for how long the board will sleep (default: 0)
    void setSleepTime(int value);
~~~
`<node_id>;<configuration_child_id>;<req>;0;<V_CUSTOM>;<function_id>,<value>`
`100;200;2;0;48;4,5`
DV's avatar
DV committed
626
627

To ask the node to start sleeping (and waking up based on the previously configured interval):
628
629
630
631
632
~~~c
    // [3] define the way the node should behave. It can be (0) IDLE (stay awake withtout executing each sensors' loop), (1) SLEEP (go to sleep for the configured interval), (2) WAIT (wait for the configured interval), (3) ALWAYS_ON (stay awake and execute each sensors' loop)
    void setSleepMode(int value);
~~~
`100;200;2;0;48;3,1`
DV's avatar
DV committed
633

634
635
636
637
638
639
To wake up a node previously configured as sleeping, send the following just it wakes up next:
~~~c
    // [9] wake up the board
    void wakeup();
~~~
`100;200;2;0;48;9`
DV's avatar
DV committed
640

641
642
643
644
645
646
The same protocol can be used to execute remotely also sensor-specific functions. In this case the message has to be sent to the sensor's child_id, with a V_CUSTOM type of message. For example if you want to collect and average 10 samples for child_id 1:
~~~c
    // [5] For some sensors, the measurement can be queried multiple times and an average is returned (default: 1)
    void setSamples(int value);
~~~
`100;1;2;0;48;5,10`
647

648
649
650
651
652
653
If you want to decrease the temperature offset of a thermistor sensor to -2:
~~~c
    // [105] set a temperature offset
    void setOffset(float value);
~~~
`100;1;2;0;48;105,-2`
DV's avatar
DV committed
654

655
Please note that anything set remotely will NOT persist a reboot apart from those provided to setSleepMode(), setSleepTime() and setSleepUnit() which are saved to the EEPROM (provided `PERSIST` is enabled).
DV's avatar
DV committed
656

657
## Understanding NodeManager: how it works
DV's avatar
DV committed
658
659
660

A NodeManager object must be created and called from within your sketch during `before()`, `presentation()`, `loop()` and `receive()` to work properly. NodeManager will do the following during each phase:

661
NodeManager::before():
DV's avatar
DV committed
662
663
664
665
* Setup the interrupt pins to wake up the board based on the configured interrupts (e.g. stop sleeping when the pin is connected to ground or wake up and notify when a motion sensor has trigger)
* If persistance is enabled, restore from the EEPROM the latest sleeping settings
* Call `before()` of each registered sensor

666
Sensor::before():
DV's avatar
DV committed
667
668
* Call sensor-specific implementation of before by invoking `onBefore()` to initialize the sensor

669
NodeManager::setup():
670
671
672
* Send a custom message with a STARTED payload to the controller
* Call `setup()` of each registered sensor

673
Sensor::setup():
674
675
* Call sensor-specific implementation of setup by invoking `onSetup()` to initialize the sensor

676
NodeManager::loop():
DV's avatar
DV committed
677
678
679
680
* If all the sensors are powered by an arduino pin, this is set to HIGH
* Call `loop()` of each registered sensor
* If all the sensors are powered by an arduino pin, this is set to LOW

681
Sensor::loop():
DV's avatar
DV committed
682
683
684
685
686
687
* If the sensor is powered by an arduino pin, this is set to HIGH
* For each registered sensor, the sensor-specific `onLoop()` is called. If multiple samples are requested, this is run multiple times.
* In case multiple samples have been collected, the average is calculated
* A message is sent to the gateway with the calculated value. Depending on the configuration, this is not sent if it is the same as the previous value or sent anyway after a given number of cycles. These functionalies are not sensor-specific and common to all the sensors inheriting from the `Sensor` class.
* If the sensor is powered by an arduino pin, this is set to LOW

688
NodeManager::receive():
DV's avatar
DV committed
689
690
691
* Receive a message from the radio network 
* If the destination child id is the configuration node, it will handle the incoming message, otherwise will dispatch the message to the recipient sensor

692
Sensor::receive(): 
DV's avatar
DV committed
693
694
* Invoke `Sensor::loop()` which will execute the sensor main taks and eventually call `Sensor::onReceive()`

695
## Examples
DV's avatar
DV committed
696
697
All the examples below takes place within the before() function in the main sketch, just below the "Register below your sensors" comment.

DV's avatar
DV committed
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
Set battery minimum and maxium voltage. This will be used to calculate the level percentage:

~~~c
    nodeManager.setBatteryMin(1.8);
    nodeManager.setBatteryMin(3.2);
~~~

Instruct the board to sleep for 10 minutes at each cycle:

~~~c
    nodeManager.setSleep(SLEEP,10,MINUTES);
~~~

Configure a wake up pin. When pin 3 is connected to ground, the board will stop sleeping:

~~~c
    nodeManager.setSleepInterruptPin(3);
~~~

Use the arduino pins to power on and off the attached sensors. All the sensors' vcc and ground are connected to pin 6 (ground) and 7 (vcc). NodeManager will enable the vcc pin every time just before loop() and wait for 100ms for the power to settle before running loop() of each sensor:

~~~c
   nodeManager.setPowerPins(6,7,100);
~~~

Register a thermistor sensor attached to pin A2. NodeManager will then send the temperature to the controller at the end of each sleeping cycle:

~~~c
   nodeManager.registerSensor(SENSOR_THERMISTOR,A2);
DV's avatar
DV committed
727
728
729
730
731
732
~~~

Register a SHT21 temperature/humidity sensor; since using i2c for communicating with the sensor, the pins used are implicit (A4 and A5). NodeManager will then send the temperature and the humidity to the controller at the end of each sleeping cycle:

~~~c
   nodeManager.registerSensor(SENSOR_SHT21);
DV's avatar
DV committed
733
734
735
736
737
738
~~~

Register a LDR sensor attached to pin A1 and send to the gateway the average of 3 samples:

~~~c
  int sensor_ldr = nodeManager.registerSensor(SENSOR_LDR,A1);
user2684's avatar
user2684 committed
739
  ((SensorLDR*)nodeManager.getSensor(sensor_ldr))->setSamples(3);
DV's avatar
DV committed
740
741
~~~

user2684's avatar
user2684 committed
742
Register a rain sensor connected to A0. This will be powered with via pins 4 (ground) and 5 (vcc) just before reading its value at each cycle, it will be presented as S_RAIN. sending V_RAINRATE messages, the output will be a percentage (calculated between 200 and 1024) and the value will be reversed (so that no rain will be 0%):
DV's avatar
DV committed
743
744
745

~~~c
  int rain = nodeManager.registerSensor(SENSOR_ANALOG_INPUT,A0);
user2684's avatar
user2684 committed
746
  SensorAnalogInput* rainSensor = ((SensorAnalogInput*)nodeManager.getSensor(rain));
DV's avatar
DV committed
747
748
749
750
751
752
753
754
755
756
757
758
759
  rainSensor->setPowerPins(4,5,300);
  rainSensor->setPresentation(S_RAIN);
  rainSensor->setType(V_RAINRATE);
  rainSensor->setOutputPercentage(true);
  rainSensor->setRangeMin(200);
  rainSensor->setRangeMax(1024);
  rainSensor->setReverse(true);
~~~

Register a latching relay connecting to pin 6 (set) and pin 7 (unset):

~~~c
  nodeManager.registerSensor(SENSOR_LATCHING_RELAY,6);
user2684's avatar
user2684 committed
760
761
~~~

762
## Example Sketches
user2684's avatar
user2684 committed
763

764
*  Analog Light and Temperature Sensor
user2684's avatar
user2684 committed
765

user2684's avatar
user2684 committed
766
767
768
769
The following sketch can be used to report the temperature and the light level based on a thermistor and LDR sensors attached to two analog pins of the arduino board (A1 and A2). Both the thermistor and the LDR are connected to ground on one side and to vcc via a resistor on the other so to measure the voltage drop across each of them through the analog pins. 

The sensor will be put to sleep after startup and will report both the measures every 10 minutes. NodeManager will take care of presenting the sensors, managing the sleep cycle, reporting the battery level every 10 cycles and report the measures in the appropriate format. This sketch requires MODULE_ANALOG_INPUT enabled in the global config.h file.

user2684's avatar
user2684 committed
770
771
772
773
774
775
776
777
778
779
780
781
782
Even if the sensor is sleeping most of the time, it can be potentially woke up by sending a V_CUSTOM message with a WAKEUP payload to NodeManager service child id (200 by default) just after having reported its heartbeat. At this point the node will report AWAKE and the user can interact with it by e.g. sending REQ messages to its child IDs, changing the duration of a sleep cycle with a V_CUSTOM message to the NodeManager service child id, etc.

~~~c
/*
NodeManager is intended to take care on your behalf of all those common tasks a MySensors node has to accomplish, speeding up the development cycle of your projects.

NodeManager includes the following main components:
- Sleep manager: allows managing automatically the complexity behind battery-powered sensors spending most of their time sleeping
- Power manager: allows powering on your sensors only while the node is awake
- Battery manager: provides common functionalities to read and report the battery level
- Remote configuration: allows configuring remotely the node without the need to have physical access to it
- Built-in personalities: for the most common sensors, provide embedded code so to allow their configuration with a single line 

783
Documentation available on: https://github.com/mysensors/NodeManager
user2684's avatar
user2684 committed
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
 */

 
// load user settings
#include "config.h"
// load MySensors library
#include <MySensors.h>
// load NodeManager library
#include "NodeManager.h"

// create a NodeManager instance
NodeManager nodeManager;

// before
void before() {
  // setup the serial port baud rate
  Serial.begin(MY_BAUD_RATE);  
  /*
   * Register below your sensors
  */
  nodeManager.setSleep(SLEEP,10,MINUTES); 
  nodeManager.registerSensor(SENSOR_THERMISTOR,A1);
  nodeManager.registerSensor(SENSOR_LDR,A2);
  /*
   * Register above your sensors
  */
  nodeManager.before();
}

// presentation
void presentation() {
  // call NodeManager presentation routine
  nodeManager.presentation();

}

// setup
void setup() {
  // call NodeManager setup routine
  nodeManager.setup();
}

// loop
void loop() {
  // call NodeManager loop routine
  nodeManager.loop();

}

// receive
void receive(const MyMessage &message) {
  // call NodeManager receive routine
  nodeManager.receive(message);
}
838
839
840
841
842
843

// receiveTime
void receiveTime(unsigned long ts) {
  // call NodeManager receiveTime routine
  nodeManager.receiveTime(ts);
}
user2684's avatar
user2684 committed
844
845
~~~

846
*  Motion Sensor
user2684's avatar
user2684 committed
847
848
849
850
851
852
853
854
855
856
857
858
859
860

The following sketch can be used to report back to the controller when a motion sensor attached to the board's pin 3 triggers. In this example, the board will be put to sleep just after startup and will report a heartbeat every hour. NodeManager will take care of configuring an interrupt associated to the provided pin so automatically wake up when a motion is detected and report a V_TRIPPED message back. This sketch requires MODULE_SWITCH to be enabled in the global config.h file.

~~~c
/*
NodeManager is intended to take care on your behalf of all those common tasks a MySensors node has to accomplish, speeding up the development cycle of your projects.

NodeManager includes the following main components:
- Sleep manager: allows managing automatically the complexity behind battery-powered sensors spending most of their time sleeping
- Power manager: allows powering on your sensors only while the node is awake
- Battery manager: provides common functionalities to read and report the battery level
- Remote configuration: allows configuring remotely the node without the need to have physical access to it
- Built-in personalities: for the most common sensors, provide embedded code so to allow their configuration with a single line 

861
Documentation available on: https://github.com/mysensors/NodeManager 
user2684's avatar
user2684 committed
862
863
864
865
866
 */

 
// load user settings
#include "config.h"
867
868
869
870
// include supporting libraries
#ifdef MY_GATEWAY_ESP8266
  #include <ESP8266WiFi.h>
#endif
user2684's avatar
user2684 committed
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
// load MySensors library
#include <MySensors.h>
// load NodeManager library
#include "NodeManager.h"

// create a NodeManager instance
NodeManager nodeManager;

// before
void before() {
  // setup the serial port baud rate
  Serial.begin(MY_BAUD_RATE);  
  /*
   * Register below your sensors
  */
  nodeManager.setSleep(SLEEP,60,MINUTES); 
  nodeManager.registerSensor(SENSOR_MOTION,3);

  /*
   * Register above your sensors
  */
  nodeManager.before();
}

// presentation
void presentation() {
  // call NodeManager presentation routine
  nodeManager.presentation();

}

// setup
void setup() {
  // call NodeManager setup routine
  nodeManager.setup();
}

// loop
void loop() {
  // call NodeManager loop routine
  nodeManager.loop();

}

// receive
void receive(const MyMessage &message) {
  // call NodeManager receive routine
  nodeManager.receive(message);
}
920
921
922
923
924
925

// receiveTime
void receiveTime(unsigned long ts) {
  // call NodeManager receiveTime routine
  nodeManager.receiveTime(ts);
}
user2684's avatar
user2684 committed
926
927
~~~

928
*  Boiler Sensor
user2684's avatar
user2684 committed
929

930
The following sketch controls a latching relay connected to a boiler. A latching relay (requiring only a pulse to switch) has been chosen to minimize the power consumption required by a traditional relay to stay on. This relay has normally two pins, one for closing and the other for opening the controlled circuit, connected to pin 6 and 7 of the arduino board. Since using a SENSOR_LATCHING_RELAY type of sensor, NodeManager will automatically consider the provided pin as the ON pin and the one just after as the OFF pin and will take care of just sending out a single pulse only when a SET command of type V_STATUS is sent to the child id. The appropriate pin will be then used.
user2684's avatar
user2684 committed
931

user2684's avatar
user2684 committed
932
In this example, the board also runs at 1Mhz so it can go down to 1.8V: by setting setBatteryMin() and setBatteryMax(), the battery percentage will be calculated and reported (by default, automatically every 10 sleeping cycles) based on these custom boundaries.
user2684's avatar
user2684 committed
933

user2684's avatar
user2684 committed
934
935
936
937
938
939
940
941
942
943
944
945
946
The board will be put to sleep just after startup and will report back to the controller every 5 minutes. It is the controller's responsability to catch when the board reports its heartbeat (using smart sleep behind the scene) and send a command back if needed. This sketch requires MODULE_DIGITAL_OUTPUT to be enabled in the config.h file.

~~~c
/*
NodeManager is intended to take care on your behalf of all those common tasks a MySensors node has to accomplish, speeding up the development cycle of your projects.

NodeManager includes the following main components:
- Sleep manager: allows managing automatically the complexity behind battery-powered sensors spending most of their time sleeping
- Power manager: allows powering on your sensors only while the node is awake
- Battery manager: provides common functionalities to read and report the battery level
- Remote configuration: allows configuring remotely the node without the need to have physical access to it
- Built-in personalities: for the most common sensors, provide embedded code so to allow their configuration with a single line 

947
Documentation available on: https://github.com/mysensors/NodeManager 
user2684's avatar
user2684 committed
948
949
950
951
952
 */

 
// load user settings
#include "config.h"
953
954
955
956
// include supporting libraries
#ifdef MY_GATEWAY_ESP8266
  #include <ESP8266WiFi.h>
#endif
user2684's avatar
user2684 committed
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// load MySensors library
#include <MySensors.h>
// load NodeManager library
#include "NodeManager.h"

// create a NodeManager instance
NodeManager nodeManager;

// before
void before() {
  // setup the serial port baud rate
  Serial.begin(MY_BAUD_RATE);  
  /*
   * Register below your sensors
  */
  nodeManager.setBatteryMin(1.8);
  nodeManager.setBatteryMax(3.2);
  nodeManager.setSleep(SLEEP,5,MINUTES);
  nodeManager.registerSensor(SENSOR_LATCHING_RELAY,6);

  /*
   * Register above your sensors
  */
  nodeManager.before();
}

// presentation
void presentation() {
  // call NodeManager presentation routine
  nodeManager.presentation();

}

// setup
void setup() {
  // call NodeManager setup routine
  nodeManager.setup();
}

// loop
void loop() {
  // call NodeManager loop routine
  nodeManager.loop();