NetReceiver is a free cloud service for collecting and monitoring remote sensor data ("sensing") and controlling devices ("actuating").

Objects

NetReceiver defines the following objects:

Protocol

NetReceiver clients communicate with the service by means of HTTP GET methods which return JSON data. Devices are identified by their unique MAC address. Devices have one or more pins, which are either analog pins (A), digital pins (D) or external pins (X). Pins are either connected to sensors which convert physical measurements, such as depth, into a voltage value or actuators which perform physical actions. Pin values are non-negative integers. A pin value of -1 denotes an error.

Configuration

Clients obtain all configuration data, i.e., the list of sensor and actuator pins and WiFi network info, from the service by means of config requests, which are sent at startup and subsequently in response to configuration changes. Clients bootstrap themselves by communicating initially via a WiFi Network named "netreceiver" with WPA password "netsender" (the default network). The clients identify themselves by means of their unique MAC address via the "ma" parameter. NetReceiver issues each client a device key, the "dk"parameter, which must be supplied with config requests. Requests for which the MAC address does not correspond to the device with the given device key are rejected. The exception is the initial config request when the client does not yet know its device key. Finally, clients may optionally supply their LAN IP address via the "la" parameter.

The format of config request is as follows:

  /config?ma=01:02:03:04:05:06&dk=12345678&la=1.2.3.4
  
Whenever the user has made a configuration change, the service returns a reconfig "rc" parameter of 1, for example:
  {"ma": "01:02:03:04:05:06", "rc": 1} 
  
Note that any response can include the "rc" parameter, not just config responses. The client then reissues a config request. Clients also issue config requests periodically if no input or output pins are currently defined.

Device configuration parameters

Parameter Description
di Device ID (when sent as a variable it is "id", not "di")
ma MAC address
dk 8-digit device key (generated by NetReceiver)
ma MAC address (e.g., "0A:0B:0C:0D:0E:0F")
wi Comma-separated SSID and key (e.g., "MySSID,MyKey")
ip Comma-separated input pin names (e.g., "A0,D1,X22")
op Comma-separated output pin names (e.g., "D2,D12")
mp Monitor period in seconds
ap Active period in seconds (for ESP clients only)
tg Software version tag (a Git tag)
rc Reconfig code (see device actions)
hw Client-specific hardware tag (not used by NetReceiver but stored locally by clients)

Sensing

The poll method sends sensed input values from the client to the service. For example, if analog port 0 (A0) reads 100 and digital port 2 (D2) reads LOW, the poll for the device with MAC 01:02:03:04:05:06 and device key 12345678 is:

  /poll?ma=01:02:03:04:05:06&dk=12345678&A0=100&D2=0
  

Actuating

The act method requests values to write to output pins, e.g.:

  /act?ma=01:02:03:04:05:06&dk=12345678
  
which returns JSON with pin output data, e.g., if D1 is to be set HIGH:
  {"ma": "01:02:03:04:05:06", "D1": 1} 
  

State

In addition to a site's configuration information, users may define variables to represent state. The vars method requests such state, e.g.:

  /vars?ma=01:02:03:04:05:06&dk=12345678
  
returning JSON variable name/value pairs:
  {"id": "MyDevice", "MyDevice.Light": "on", "MyDevice.Camera": "off", ...}
  

Device actions

Reconfig "rc" parameters can be used for more than just device reconfiguation. For example, the Raspberry Pi client implements the following, shown with their corresponding NetReceiver status icon.

The status icon remains in effect until the action completes, when it reverts to the ready state ().

Upgrading is a 3-step process as follows:

  1. Update the device tag to the desired tag, e.g., from "v1.0" to "v1.1".
  2. Once the device is ready, initiate the upgrade.
  3. Once the device is ready, reboot the device for the upgrade to take effect.
If the device remains stuck in the upgrade state, it means the upgrade has failed. If this happens, updating or rebooting the device will reset things.

Variables

A NetReceiver variable is simply a string. Boolean variables are variables for which a value of "1", "true" or "on" is treated as logical true. A value of "0", "false" or "off" is logical false, as is a variable that is not defined.

When variables are mapped onto actuator pin values, logical true is sent as integer 1 and false as integer 0. Other integers are sent as is.

The var sum, denoted "vs", is a 32-bit CRC-style checksum of the current variables and their values which is returned as part of each response. Clients are responsible for comparing the latest "vs" value with their cached value to determine if their variables are out of date. Clients then reissue a /vars request.

Triggers and crons

Triggers perform actions resulting from specified sensor conditions, e.g., a voltage is less than a specified value. Triggers have optional preconditions, which are simply one or more boolean variables which must all be true in order for the trigger to fire. Triggers with preconditions are evaluated prior to those without preconditions (in the same order as displayed). Triggers executed previously can set variables which are read or modified by subsequent triggers.

Crons perform actions based on specified times of the day. To perform an action for an interval of time requires one cron to start and another to finish.

For example, one trigger or cron may set the "Alarm" variable to "on" (true) and another may set it to "off" (false). Further, other triggers may specify "Alarm" as a precondition and will only fire when "Alarm" is true.

Notifications

NetReceiver sends notification emails from NetReceiverService@gmail.com, so ensure this address is not treated as spam by your email provider.

Client

The client is known as NetSender, which is also the name of the client library. The default client is gpio-netsender. There is an Arduino C++ version for the ESP8266 microcontroller (based on the Adafruit HUZZAH ESP8266 breakout) and a Go version for the Raspberry Pi. You may install multiple clients at multiple locations at your site. Note that a WiFi connection is required and the ESP8266 only operates in the 2.4Ghz WiFi band.

Setup

You will need to know the client device's MAC address in order to register it with NetReceiver. Once you have this information, go to your site's Settings page and create a Device object with the given MAC address. Also specify the WiFi network that you wish to use. The other parameters can be specified later.

When a NetSender powers up it first tries to connect to the default network, which is a WPA/WPA2 WiFi network named "netreceiver" with the password "netsender". Any easy way to do this is to temporarily set up your smart phone's hotspot (tethering) this way. Do not use the default network as your device's permanent WiFi settings as it is only intended to be used as the fallback network.

If a NetSender cannot connect to the last saved network it will attempt to connect to the default network and will continue to do so indefinitely.

Note that NetSender does not require a WiFi connection that is either permanent or 100% reliable. NetSender will keep trying to reconnect until it is successfully able to connect.

Monitor Period vs. Active Period

The monitor period for a device is the number of seconds between monitor/actuation cycles. The active period is the number seconds that the device is not deep sleeping. In stateless monitoring applications a NetSender can wake up from a deep sleep, measure inputs and go straight back go back to deep sleep. An active period is required however when actuating pins or handling interrupts. If the active period equals the monitor period then the device never enters deep sleep.

Extending the Client

The NetSender library and default client, gpio-netsender, has support for reading values from analog (A) and GPIO digital (D) pins. For sensors that require more work than simply reading a pin, e.g., reading a data sequence or counting interrupts, you'll need a custom client. NetReceiver makes this possible with the concept of external pins prefixed with an "X", i.e., "X0", "X1", etc. You simply map these virtual pins to your custom sensor functions. NetReceiver treats external pins like regular pins, allowing you to define sensors and triggers, etc. See dht-netsender and weather-netsender for examples.

External pins

External pins are "X" followed by 2 or 3 digits. The first digit of a 2-digit pin (or first two digits of a 3-digit pin) denotes the device ID and last digit denotes the quantity. No more than 10 quantities can be assigned to a single device ID, however a second ID can be assigned to the same physical device if more than 10 quantitites are required. While digits representing devices are unique, digits representing quantities are not. For example, temperature may be quantity #0 for one type of temperature sensor or quantity #2 for a different type of sensor.

Number Device Quantity
00 ~ 09 Custom Not assigned
10 ESP CPU clock count
20 Raspberry Pi CPU utilization
21 Raspberry Pi CPU temperature
30 SDLWR Wind speed
31 SDLWR Wind gust speed
32 SDLWR Wind direction
33 SDLWR Precipitation
40 DHT11 Temperature
41 DHT11 Humidity
50 DHT22 Temperature
51 DHT22 Humidity

ESP Arduino client

LED

By default, the ESP8266 Arduino client uses the blue LED to signal various conditions as follows:

Pulse mode

Pulse mode enables the ESP8266 Arduino client to drive the blue LED and GPIO pin 2. The shape of the pulse is controlled by external output pins X10 through X13. These parameters are saved to the EEPROM and once configured, pulsing does not require network connectivity. X14, if present and true, suppresses the pulse. X14 is not stored in EEPROM to avoid permanently suppressing the pulse due to loss of network. To permanently disable pulsing remove X10 and X11 from the outputs.

Pulse mode

Attributes and codes

The following attribute codes are used in HTTP params and JSON replies:

Experimental methods

NetReceiver has experimental support for receiving, storing and forwarding video as MPEG Transport Stream (MPEG-TS or MTS). This must be enabled by the NetReceiver administrator.

Video in the form of short clips (typically 1 second) is uploaded as poll method POST data with the video size encoded as video ("V") query params, starting with V0. Multiple videos concatenated in a single body must be in the same order as the video IDs in query params. Therefore V0=52640&V1=64672 represents a video of 52640 bytes in size followed by a video of 64672 bytes. The full URL is as follows:

  /poll?ma=01:02:03:04:05:06&dk=12345678&V0=52640&V1=64672
  

Recent video may also be downloaded using the experimental video method. For example, to download video V0 originating from a device named DEV:

  /video/KEY/DEV.V0
  

where KEY is either the site key or an application-specific password granted by the site's administrator.

In addition to being stored, MPEG-TS video can be forwarded to endpoints as either raw UDP or RTP. Endpoints, which are configured in the Endpoints section of the settings page, must have globally public IP addresses in order to be visible to App Engine. Video will be streamed to an endpoint from the time it is enabled until the specified timeout, at which point the endpoint will be automatically disabled. Note that endpoints cannot request streaming; all control is by NetReceiver.

License

NetReceiver is Copyright © 2017-2018 Alan Noble.

NetReceiver is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

NetReceiver is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for details.