Accessing Raw Data Remotely

Bryan Mayland edited this page Jul 16, 2017 · 11 revisions

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 (/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.

Discovery

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 /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"
        }
      ]
    }
  ]
}

Version

API version 1 (GET) - /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)

Current Status

API version 1 (GET) - /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 /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"

HeaterMeter Configuration

API version 1 (GET/POST) - /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. /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/luci/lm/set or curl --data "sp=250&pn0=Pit" http://heatermeter.local/luci/lm/set?apikey=XXXX or for just a single parameter curl --data "value=250" http://heatermeter.local/luci/lm/set/sp?apikey=XXXX

AVR Firmware Upload

API version 1 (POST) - /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/luci/lm/api/fw?apikey=XXX"

Streaming Status

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

Historical Data

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
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.