NetReceiver is a free cloud service for collecting and monitoring remote sensor data ("sensing") and controlling devices ("actuating"). NetReceiver clients are called NetSenders.
NetReceiver is based on the idea of keeping clients very simple and putting as much processing as possible into NetReceiver. Read about these principles here.
Read about the ESP8266 Arduino client here.
NetReceiver defines the following objects:
NetReceiver clients communicate with the service by means of HTTP requests which return JSON data. Devices are identified by their unique MAC address. Devices in turn have one or more pins, which are either associated with sensors which convert physical measurements or actuators which perform physical actions.
NetReceiver JSON values are described here.
Despite the name, pins represent more than just physical device pins. In NetReceiver, pins represent different data types. Scalar pins represent non-negative integers, with -1 signifying an error. Scalar values are sent as URL encoded parameters in the HTTP request. Vector pins represent everything else, i.e., any value that cannot be represented as a single non-negative, number. Vector data is sent in the body of a HTTP POST request.
Pins may be further classified as real or virtual. Real pins, such as analog or digital (GPIO) pins, are attached to a physical device. Virtual pins, on the other hand, provide an additional layer of abstraction. For example, while a DHT22 combined temperature/humidity sensor is physically connected to a single GPIO pin, extracting useful data requires additional computation. In this case, two scalar "X" pins suffice to convey computed temperature and humidity values. A more complicated example is video where a single "V" pin represents one channel of video data.
Name | Type | Description |
---|---|---|
A | Scalar | Analog value |
B | Vector | Binary data |
D | Scalar | Digital value |
S | Vector | Sound (audio or sonar) data |
T | Vector | Text (log or GPS) data |
V | Vector | Video data |
X | Scalar | Software-defined sensor value |
By convention, pin numbers start from 0, not 1. For example, A0 is the first analog output (or only analog output in the case of the ESP8266), V0 is the first video channel, etc. Log data is typically reported as the first text output, namely T0, and GPS data, if present, is reported as T1.
Clients obtain 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.4Whenever 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.
Devices are configured under Settings. The ESP8266 client is configured 100%
this way, however the Raspberry Pi client requires some
pre-configuration via /etc/netsender.conf. Specifically,
the MAC address (ma) and device key (dk) must be
manually specified in /etc/netsender.conf before the client
can run as a NetSender client. Other parameters are updated
automatically.
Parameter | Description | Example |
---|---|---|
di | Device ID (when sent as a variable it is "id") | "esp-10" |
ma | MAC address (required in netsender.conf for Pi) | "0A:0B:0C:0D:0E:0F" |
dk | 8-digit device key (generated by NetReceiver; required in netsender.conf for Pi) | 01234567 |
wi | Comma-separated SSID and key | "MySSID,MyKey" |
ip | Comma-separated input pin names | "A0,D1,X22" |
op | Comma-separated output pin names | "D2,D12,X10" |
mp | Monitor period in seconds | 60 |
ap | Active period in seconds (for ESP clients only) | |
tg | Software version tag (a Git tag) | "v1.2" |
rc | Reconfig code | See device actions |
hw | Client-specific hardware specifier (not used by NetReceiver but saved by clients) | "dhtPin=22" |
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
The act method requests values to write to output pins, e.g.:
/act?ma=01:02:03:04:05:06&dk=12345678which returns JSON with pin output data, e.g., if D1 is to be set HIGH:
{"ma": "01:02:03:04:05:06", "D1": 1}
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=12345678returning JSON variable name/value pairs:
{"id": "MyDevice", "MyDevice.Light": "on", "MyDevice.Camera": "off", ...}
Reconfig "rc" parameters can be used for more than just device reconfiguation, shown below with their corresponding NetReceiver status icon.
The status icon remains in effect until the action completes,
when it reverts to the ready state ().
Debug mode remains in effect until the device is updated.
Upgrading is a 3-step process as follows:
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.
Variables can be global, i.e., Var, or local to a device, i.e., Device.Var. Global variables are shared across all devices, whereas local variables are only accessible to the given device.
When variables are mapped onto actuator pin ervalues, 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 poll or act 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.
There are two special variables which are always included, namely id and mode. The former is the ID assigned to the device by the user (not to be confused with the MAC address). The latter represents the client's operating mode. Clients may set arbitrary values for the mode but conventionally Normal signifies the default mode and Paused signifies that the client is paused in some way (case sensitive). Clients should therefore check the mode value and act accordingly.
While most variables flow one way from NetReceiver to the client, clients may communicate mode changes in the other direction. This is done by adding the md parameter to the /vars request. For example:
/vars?ma=01:02:03:04:05:06&dk=12345678&md=SpecialUpon success, the /vars response always includes the new value for the mode. Also, as for other variables, changes to mode can fire triggers.
Sensors transform raw pin values into useful measurements, including binary data. NetReceiver includes a number of built-in functions to make this easy. These generally take comma-separated values of floating-point numbers. Additional custom functions can be defined in code, in which case the single argument is the name of the function that performs the custom transformation.
Name | Args | fn(x) | |
---|---|---|---|
none | x | ||
scale | a | a * x | |
linear | a,b | a * x + b | |
quadratic | a,b,c | a * x2 + b * x + c | |
custom | fn | fn(x) |
Device | Type | ||
---|---|---|---|
ESP | 1 | ||
Pi | 2 | ||
SDLWR | 3 | ||
DHT11 | 4 | ||
DHT22 | 5 | ||
DS18B20 | 6 |
Device | Number | Input quantity | Output quantity |
---|---|---|---|
Custom | 00 ~ 09 | Not assigned | Not assigned |
ESP | 10 | Analog (A0) value | |
ESP | 11 | Alarm (bool) | |
ESP | 12 | Alarm count | |
ESP | 13 | Boot reason | |
ESP | 14 | Suppress pulse (bool) | |
Pi | 20 | CPU temperature | |
Pi | 21 | CPU utilization | |
Pi | 22 | Virtual memory | |
SDLWR | 30 | Wind speed | |
SDLWR | 31 | Wind gust speed | |
SDLWR | 32 | Wind direction | |
SDLWR | 33 | Precipitation | |
DHT11 | 40 | Temperature | |
DHT11 | 41 | Humidity | |
DHT22 | 50 | Temperature | |
DHT22 | 51 | Humidity | |
DS18B20 | 60 | Temperature |
NB: This functionality is migrating from NetReceiver to VidGrind.
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 recv 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:
/recv?ma=01:02:03:04:05:06&dk=12345678&V0=52640&V1=64672
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.
Other binary and text data may also be sent to NetReceiver using the recv method, using pin types B and T respectively. Binary data can be used for audio.
Recent data can be downloaded using the video, audio and text methods respectively. For example, to download video V0 originating from a device named DEV:
/video/KEY/DEV.V0KEY is either the site key or an application-specific password granted by the site's administrator.
Here is another example for text data for a specific date/time range:
/text/KEY/DEV.T0?ds=START&df=FINISHor for a duration from a start time:
/text/KEY/DEV.T0?ds=START&dd=DURATION&du=UNITSSTART and FINISH are times are ISO-format date/time strings, i.e., "YYYY-MM-DD HH:MM", or a time string "HH:MM", DURATION is a number and UNITS is one of minutes (default), hours or days.
VidGrind and VidRecord are experimental servers written in Go that implement video capture and processing. These can be found under the ausocean/iotsvc repository.