-
Notifications
You must be signed in to change notification settings - Fork 83
Accessing Raw Data Remotely
This list may not always be fully up to date. The JSON data is pretty self-explanitory so always refer to a live LinkMeter system for the most up-to-date parameter information. This documentation refers to the LinkMeter v14 and above with dedicated REST API, for information about older access methods, refer to Accessing Raw Data Remotely (v13 and below)
All read functions must be called with the GET HTTP method. All write functions must be called with the POST HTTP method. Write functions also require a valid API key obtained from the configuration webui page. The key can either be added as part of the request URI with the name apikey (/cgi-bin/luci/lm/api/set?apikey=XXXX) or as part of the POST body. POST bodies should use the application/x-www-form-urlencoded MIME type.
LinkMeter includes support for autodiscovery of devices via the ZeroConf/mDNS/DNS-SD (Bonjour/Avahi) protocol. The service is advertised as an _http._tcp (Web Site) service with the name HeaterMeter BBQ Controller on %h where %h is the hostname. The txt record contains a path key which is the URI of the LinkMeter webpage. All REST API functions are under the URI /cgi-bin/luci/lm/api
A second method of finding devices on the user's network is to query the HeaterMeter Device Registry by GETing the URL https://heatermeter.com/devices/?fmt=json. A JSON object will be returned which lists the internal IP addresses for interfaces on the device. This list will only be populated if the request is made from the same public IP address as the device (they are both NATed through the same home router). That is, if the request is made from the cellphone network and the device is on home wifi, the device will not be found. Look through the interface list for an IP address with a non-zero packet count. Multiple devices may be found as illustrated below.
{
"ip": "47.198.193.115",
"total": {
"all": 2006,
"week": 244,
"month": 628
},
"devices": [
{
"device_id": "1952",
"model": "BCM2835",
"revision": "000e",
"serial": "0000000091752c9f",
"hostname": "BencHM",
"seen": "1498592611",
"uptime": "54",
"interfaces": [
{
"name": "eth0",
"addr": "192.168.200.1",
"packets": "0"
},
{
"name": "wlan0",
"addr": "192.168.2.16",
"packets": "44"
}
]
},
{
"device_id": "1746",
"model": "BCM2835",
"revision": "0010",
"serial": "0000000078c7f575",
"hostname": "BencHM",
"seen": "1498670612",
"uptime": "55",
"interfaces": [
{
"name": "eth0",
"addr": "192.168.200.1",
"packets": "0"
},
{
"name": "wlan0",
"addr": "192.168.2.16",
"packets": "59"
}
]
}
]
}
API version 1 (GET) - /cgi-bin/luci/lm/api/version
First thing an application wishing to interface with LinkMeter should do is query the version to determine the API version and what functions are available.
{
"ucid": "20161230B",
"api": 1
}
| Field | Example | Description |
|---|---|---|
| api | 1 | Current version of the API. Each function in the documentation indicates what API version it was added |
| ucid | 20161230B | If HeaterMeter is present, this field will contain the version string for the AVR firmware. May not be present or value maye be null. |
The HTTP result codes for this URL are unique in that it is a READ API that can return a 403 Forbidden code, indicating the user has disabled the API.
| HTTP Result | Text | Description |
|---|---|---|
| 403 | Forbidden | User has explicitly disabled external API (API exists but even read access is denied) |
| 404 | Not found | LinkMeter v13 or below. API functions are not available, application should fall back to Accessing Raw Data Remotely (v13 and below) |
API version 1 (GET) - /cgi-bin/luci/lm/api/status
The current status (probe temperatures, etc) in JSON format. Values from inside the current status JSON object can be requested by appending a path to the request URI. Array objects are referenced by their 0-based index. For example, to request the name of probe 0, request /cgi-bin/luci/lm/api/status/temps/0/n. If the request is specific enough to result in a single value, the returned MIME type is text/plain as the result is no longer a valid JSON object. If a value is not found, null is returned.
{
"time":1405429467,
"set":65,
"lid":38,
"fan":{"c":0,"a":13,"f":10},
"adc":[0,0,0,0,0,3],
"temps":[
{
"n":"Probe 0",
"c":78.6,
"dph":1.3,
"rf":{"s":1,"b":0},
"a":{"l":-40,"h":200,"r":null}
},
...
]
}
| Field | Example | Description |
|---|---|---|
| time | 1405429467 | Current time (hopefully in UTC) in UNIX timestamp format (example is Tue, 15 Jul 2014 13:04:27 UTC). Might be incorrect if device has no Internet access. |
| set | 65 | PID Set Point (can be C or F but doesn't specify) |
| lid | 38 | Lid Open countdown timer. Number of seconds remaining in lid mode or 0 if lid mode is off |
| fan.c | 0 | Current PID output percentage |
| fan.a | 13 | Average PID output percentage over last few minutes |
| fan.f | 10 | Current fan output percentage (restricted by min/max fan speed) |
| adc[] | 0,0,0,0,0,3 | ADC noise range indicator. Probe 0 is adc[5], Probe 1 is adc[4], etc. May be absent if not supported. |
| temps[X].n | Probe 0 | Name assigned to probe |
| temps[X].c | 78.6 | Current probe temperature |
| temps[X].dph | 1.3 | Degrees per hour calculated (least squares linear fit). May be null if not enough data, or missing if not supported |
| temps[X].a.l | -40 | Probe alarm low trigger. Negative numbers indicate alarm is disabled |
| temps[X].a.h | 200 | Probe alarm high trigger. Negative numbers indicate alarm is disabled |
| temps[X].a.r | null | Probe alarm ringing. "L" or "H" if the alarm is currently triggered or null if no alarm ringing |
| temps[X].rf.s | 1 | Assigned RF node signal strength 0-3. The RF object is not present if the probe is not of type "RF" |
| temps[X].rf.b | 0 | Assigned RF node battery low (0=OK, 1=Low). The RF object is not present if the probe is not of type "RF" |
API version 1 (GET/POST) - /cgi-bin/luci/lm/api/config
Perform a GET request to return the current HeaterMeter configuration JSON object. Like the status request, specific individual parameters can be returned by adding a path to the URI (e.g. /cgi-bin/luci/lm/api/config/sp). Perform a POST request to the base URI to set one or more parameters by name in the POST body, which will return a text/plain result. For a list of settable parameters see, URLs and Commands
GET: application/json
{
"sp": 225,
"fflor": 0,
"smax": 200,
"ld": 30,
"lb": "10",
"pidp": 5,
"fmin": 0,
"pt2": "1",
"pca2": "7.3431401e-4",
"le1": "10",
"pt3": "1",
"pn2": "Probe 2",
"fsmax": 100,
"pn3": "Probe 3",
"prfn2": "",
"pcc2": "9.5156869e-8"
...
}
POST: text/plain
User api_write setting 2 values...
sp to 250 = OK
pn0 to Pit = OK
Done!
Example cURL requests: curl --data "sp=250&pn0=Pit&apikey=XXXX" http://heatermeter.local/cgi-bin/luci/lm/set or curl --data "sp=250&pn0=Pit" http://heatermeter.local/cgi-bin/luci/lm/set?apikey=XXXX or for just a single parameter curl --data "value=250" http://heatermeter.local/cgi-bin/luci/lm/set/sp?apikey=XXXX
API version 1 (POST) - /cgi-bin/luci/lm/api/fw
The AVR firmware can be updated remotely by posting a IHEX formatted file. The file should be included in the POST body with the field name hexfile and is required or a 403 error will be returned.
Example cURL request: `curl --form hexfile=@"path/to/local/heatermeter.hex" "http://heatermeter.local/cgi-bin/luci/lm/api/fw?apikey=XXX"
The current status can also be streamed using the HTTP server-sent events protocol from the URI /luci/lm/stream. Updates are sent with between 1 and 5 seconds, depending on changes in the data.
Content-Type:text/event-stream
event: hmstatus
data: {"time":1405429467,"set":65,"lid":38,...}
event: hmstatus
data: {"time":1405429469,"set":65,"lid":36,...}
event: hmstatus
data: {"time":1405429471,"set":65,"lid":34,...}
| Event | Description |
|---|---|
| hmstatus | Current Status update |
| log | Debugging log message |
| alarm | Alarm was just triggered |
| peaks | Last high and low Pit peaks |
| pidint | PID internals dump enabled by the user |
Graph data is in CSV format and is accessible from the URI /luci/lm/hist. The fields are UNIX timestamp, Setpoint, Probe 0, Probe 1, Probe 2, Probe 3, Lid Open. Probe fields can be "nan" if no probe was inserted at the time. Requesting the data with no parameters will autoscale and return the best range of data to fit the amount stored in the database. Adding the nancnt=X parameter to the query can adjust the range.
| nancnt | Range |
|---|---|
| 460 | 1 hour |
| 360 | 6 hours |
| 240 | 12 hours |
| 0 | 24 hours |
1405344600,65,94.043333333333,nan,44.475555555556,82.325555555556,0
1405344780,65,93.503333333333,nan,44.792222222222,82.635555555556,0
1405344960,65,93.166388888889,nan,45.036111111111,82.865,0
1405345140,65,92.903611111111,nan,45.281111111111,83.07,0
1405345320,65,92.672777777778,nan,45.592222222222,83.1,0
1405345500,65,92.414444444444,nan,45.794444444444,83.211111111111,0
1405345680,65,92.141111111111,nan,46.016666666667,83.473333333333,0
1405345860,65,92.037777777778,nan,46.314444444444,83.727222222222,0
1405346040,65,92.362222222222,nan,46.534444444444,83.935555555556,0
1405346220,65,92.021666666667,nan,46.795,84.147777777778,0
1405346400,65,91.818888888889,nan,46.982222222222,84.41,0
1405346580,65,91.867777777778,nan,47.156666666667,84.571111111111,0
1405346760,65,91.804444444444,nan,47.404444444444,84.6,0
1405346940,65,91.769444444444,nan,47.621111111111,84.626666666667,0
1405347120,65,91.727777777778,nan,47.796666666667,84.707777777778,0
1405347300,65,91.587222222222,nan,47.982222222222,84.888888888889,0
1405347480,65,91.707777777778,nan,48.182222222222,84.751111111111,0