 |
The neatMon Open Source API provides a convenient way to integrate the Automated Monitoring Nodes into third-party platforms. |
¶ Overview
This reference manual is designed to answer questions about the open-source API and how to integrate the Automated Monitoring Nodes into third-party platforms for OEM and research purposes. The manual below focuses on the methods contained in the Open Source API as they are currently implemented.
To get started with the API it is recommended to watch the technical video and to set up the API locally using the guides below. Then perform HTTP Post requests with Postman using the GitHub HTTP Post Body example below.
Note: The API has been updated since the time of posting, and includes new features, however getting started and performing an HTTP Post should be the same.
¶ Sample API
The sample neatMon provides is designed to be a reference to enable users to set up a server. The example uses Docker, node js, express, and MongoDB. The container management tool called Docker orchestrates bringing up the database and web services, which is helpful for testing and development purposes. In a production environment, best practices should be employed and it is recommended to consult with the neatMon Professional Services Team
Open source nM API source code
License Type: MIT
¶ Web Services Reference
The automated monitoring nodes currently support HTTP POST and will be supporting MQTT soon. This guide will focus on the HTTP POST methods of communication.
¶ Communication Workflow
When a device sends data to the API server, it sends data in the body of an HTTP POST using the JSON format below. In response, the node is expecting to receive the current time in the body of the response as well as a code 200.
The device data contained in the HTTP POST is a function of the device configuration and sensors that have been configured.
¶ Node Configurations
In the node firmware configuration menu, the network sub-menu provides the ability to set a host address, route, and port number. Additionally, the sync rate is configurable to periodically send data to the remote server.
¶ Server Requirements
The server must accept incoming HTTP Post requests, similar to the example JSON payload in the sample API documentation. Note: the port can be configured in the node firmware.
When multiple nodes are deployed, many POST requests can be submitted simultaneously so it is important to utilize async requests and workers.
¶ HTTP POST
The node will send an HTTP Post request, at a configured interval, or during the initial bootup sequence containing data, and current configuration, similar to the following.
¶ HTTP Post Header
The node will send a header containing the following data:
POST /api/device/81a8e7b1-bf35-8d4e-d48afcaf9218 HTTP/1.1
Host: api.neatmon.io:1330
Connection: close
Content-Type: application/json
CRC-32: 3140f0b0
Content-Length: 59The first line indicates the HTTP request type, the path the server should operate on, and the HTTP version to use.
| Parameter | Description |
|---|---|
| Host | The domain name of the server and the port to use |
| Connection | Indicates what to do with the connection after transmission is finished |
| Content-Type | The media type being transmitted |
| CRC-32 | The CRC-32 of the post body |
| Content-Length | The content length of the post body |
¶ HTTP POST Body
The node will send an HTTP Post request, at a configured interval, or during the initial bootup sequence containing data, and current configuration, similar to the following.
{
"id":"f9218",
"pn":"PLUS",
"hw":106,
"fw":258,
"v": {
}
}
¶ HTTP POST Body Keys
Note that the id key is the only required key when a node performs a POST request. It is recommended to maintain a database table of provisioned devices that have been added to the platform so that incoming POST requests can be validated against the list of provisioned devices.
| Name | Required | Description | Data Type | Modifier |
|---|---|---|---|---|
| id | Yes | The ID is the last 5 characters of the device's GUID or globally unique identifier. Generated by a hardware key on the device | String | |
| pn | No | The abbreviated part number of the node | String | |
| hw | No | The hardware version of the node | Int | x / 10 |
| fw | No | The firmware version of the node | Int | x / 10 |
| cfg | No | The current configuration of the node | String | |
| v | No | Data records (values) in an array format. Values may or may not be present depending on AMN port configuration | String (Array) |
¶ Data (v) Records
Data records are grouped by type of sensor and time recorded. An example is provided for reference.
In the example below, the sensor has two sets of data records. Each set also has other values associated with it, in the case of the temperature and humidity sensor both values, as well as the time, are provided.
"tprh0":[
{
"t":74,
"h":18,
"ts":2191248
},
{
"t":10,
"h":38,
"ts":2259341
}
]¶ Timestamp
The time stamp will be provided with each sensor data set as follows
| Name | Description | Data Type | Modifier |
|---|---|---|---|
| ts | The timestamp is the EPOCH time, or seconds since January 1st, 1970 | Long int |
¶ Note regarding data records and formatting
The node is capable of sampling any number of sensors. To help differentiate between different types of sensors, we try to include a short one to three-character descriptor for each value and sub-value. In the example above the sensor configured is tprh0, while t and h represent temperature and humidity respectively.
See the sensor configuration guides for specific details regarding the data formats.
¶ HTTP Post Server Response Header
HTTP/1.1 200 OK
X-Powered-By: Express
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 494
Date: Mon, 30 Sep 2024 23:57:42 GMT
X-RateLimit-Reset: 1727741303
Content-Type: application/json
Content-Length: 185
CRC-32: a0ac6298
Connection: keep-alive
Keep-Alive: timeout=61¶ HTTP Post Response Body
After making an HTTP Post request, the server shall respond to the Automated Monitoring Node with the epoch current time. In some cases, an over-the-air firmware or configuration update may be required from the server/platform. To perform this, the server must include additional keys in the HTTP response body.
¶ Time Stamp
The server shall always respond with the current epoch time (GMT) for each HTTP Post request.
The example below is the epoch time for GMT: Tuesday, December 19, 2023, 11:35:32 PM
{
"t": 1703028932
}¶ Configuration Updates
Configuration updates, control requests, and firmware can all be sent to the node over the air as part of the HTTP response body using the cmd key.
The following are supported
| Key | Description |
| control | Control events |
| fwu | Firmware over-the-air updates |
| cfg | Configuration changes |
Documentation for each method is further explained in the user manual for sensor configurations, and the firmware reference manual.
An example response is shown below utilizing each method:
{
"t": 1703036628,
"cmd": {
"control": [
{
"rnum": 1,
"rtyp": 1,
"on": 1703037600,
"off": 1703041200
},
{
"rnum": 2,
"rtyp": 3,
"on": 1703036700,
"off": 1703038500,
"on_cmd": "21R1,1",
"off_cmd": "21R1,0"
}
],
"fwu": {
"uri": "http://api.neatmon.io:1330/files/amn-w-firmware-v191.bin"
},
"cfg": {
"sens": [
{
"p": 1,
"t": "av",
"c": {
"m": 123,
"b": 123
}
}
]
}
}
}