Skip to content

Changes for 6MW-series devices

The Auditor 6MW is the first Wattwatchers device to feature dual communications transports—cellular (LTE/4G) and WiFi (2.4Ghz).

Additionally, this dual transport feature enables configuration of WiFi credentials (and other parameters in the future) via the API, as we can emit these changes to the device over cellular, rather than relying on being in the proximity of a device to configure via a custom WiFi access point (as is the case with the Auditor 6W product).

This document outlines the necessary changes to how the REST API works to support these new features, introduced in v3.6.0 of the API, April 2024.

This document augments our publicly accessible documentation and assumes you are already across that documentation.

Device status

When accessing the GET /devices/{device-id} endpoint for a 6MW or 6MW-CER device, the following changes apply.

Device model

The model property now reports 6MW or 6MW-CER, corresponding to the device model.

Switches

The switches object will list one switch for the 6MW-CER. All other functionality, except the number of switches, is the same as other switching models (e.g. 6M+3SW).

Comms

The comms object in the status has been extensively updated to support the dual-transport nature of the 6MW and 6MW-CER devices.

For an active 6M device, the API currently returns:

{
  ...
  "comms": {
    "type": "cellular",
    "mode": "4G",
    "cellQuality": 3,
    "lastHeardAt": 1710983656,
    "signalQualityDbm": -85,
    "simId": "8942310019001078062",
    "apn": "soracom.io",
    "imsi": "502122400100455",
    "networkId": "Telstra Mobile"
  },
  ...
}

And for 6W devices, the API returns:

{
  ...
  "comms": {
    "type": "wifi",
    "macAddress": "4C:55:CC:1A:F4:ED",
    "lastHeardAt": 1657415526,
    "signalQualityDbm": -39,
    "networkId": "Telstra356F0A"
  },
  ...
}

For backwards compatibility, the API will report the relevant values for the last known–good values reported by a 6MW-series device.

Cellular

For example, when the device is active on cellular, the API will return:

{
  ...
  "comms": {
    "apn": "soracom.io",
    "cellQuality": 3,
    "imsi": "502122400100455",
    "lastHeardAt": 1710914072,
    "mode": "4G",
    "networkId": "Optus"
    "signalQualityDbm": -100,
    "simId": "8942310019001078062",
    "type": "cellular,wifi",
  },
  ...
}

type has been updated to match the dual-transport nature of the device, returning cellular,wifi (instead of just cellular or wifi as per previous models). Note that type refers to the capabilities of the device, not what is active at a given time.

The mode property indicates what is active. This property previously reported the type of cellular connection last used by a device—i.e. it could be 3G or 4G. We have carried this behaviour forward, but as 6MW-series devices are currently only capable of LTE/4G operation, it will always be 4G when in cellular mode.

Note that WiFi-related properties (such as macAddress) are NOT returned when the device is operating on cellular. The networkId also reflects the type of transport. In the example above, it indicates the device was last active on the Optus cellular network.

signalQualityDbm is always -1 (Unknown) for 6MW devices running firmware version 0.12.1 and below. Devices running firmware version 0.13.0 and above report this value correctly.

WiFi

When a 6MW-series device is active on WiFi, the API will return:

{
  ...
  "comms": {
        "type": "cellular,wifi",
        "macAddress": "c0:49:ef:03:62:d4", 
        "mode": "wifi",
        "lastHeardAt": 1710914272,
        "signalQualityDbm": -43,
        "networkId": "My home SSID"
    },
  ...
}

Note that mode changes to wifi when the device is active. (mode was not previously returned for 6W devices.)

networkId reports the SSID that the device last connected on, when WiFi was the last known active transport. i.e. this property reports different values depending on the transport that is active.

Additional properties

The API returns three additional comms properties for 6MW and 6MW-CER devices:

  • lastHeardVia
  • cellular
  • wifi
{
  ...
  "comms": {
    "apn": "soracom.io",
    "cellular": { ... },
    "cellQuality": 3,
    "imsi": "502122400100455",
    "lastHeardAt": 1710914072,
    "lastHeardVia": "cellular",
    "mode": "4G",
    "networkId": "Optus"
    "signalQualityDbm": -100,
    "simId": "8942310019001078062",
    "type": "cellular,wifi",
    "wifi": { ... },
  },
  ...
}

lastHeardVia reports which transport we last heard from the device over. It will be either cellular or wifi. While this is very similar to the mode property, as noted above mode may evolve in the future to show what type of network is connected (e.g. 2G or 5G).

lastHeardVia also matches the names of the next two properties, so you can do programmatic look-up of the new sub-objects using this value. For example, in Javascript pseudo-code:

 active = status.comms[status.comms.lastHeardVia]

comms.cellular

{
  ...
  "comms": {
    ...as outlined above..
    "cellular": {
      "apn": "soracom.io",
      "carrier": "Optus",
      "imsi": "502122400185274",
      "lastHeardAt": 1710914072,
      "mode": "4G",
      "signalQuality": 2,
      "signalQualityDetail": {
        "rsrq": -140,
        "rsrp": -12,
        "rssi": -41
      },
      "signalQualityLabel": "Poor",
      "simId": "8942310722001172740"
    }
    ...
  },
  ...
}

The cellular sub-object lists all of the last known properties relating to the cellular transport, regardless of which one is currently active. i.e. if a device last communicated via WiFi, this object will still be returned in its entirety. This is different to the comms-level properties, which are transient depending on the active transport.

This becomes especially important for troubleshooting WiFi issues, where you need to know the last known set values, even if the device has fallen back to cellular due to WiFi-related failures.

In addition to the properties that are provided for previous devices (such as 6M-series devices), the 6MW reports some additional values.

comms.cellular.lastHeardAt reflects when the device last communicated using the cellular transport. This differs from the comms.lastHeardAt which shows the last time we heard from the device no matter what transport was active. Under normal conditions, comms.lastHeardAt will match either the comms.cellular.lastHeardAt or comms.wifi.lastHeardAt values.

signalQuality is a 10-point scale (a value between 0 and 9) representing the reported signal quality based on the RSRQ and RSRP values reported by the LTE module, based on this matrix:

RSRP
< -112 > -112 > -108 > -104 > -100 > -96 > -92 > -88 > -84 > -80
RSRQ > -4 0 3 4 7 8 8 9 9 9 9
> -5 0 3 4 6 7 8 8 9 9 9
> -6 0 1 3 4 6 7 8 8 9 9
> -8 0 1 3 4 5 6 7 8 8 9
> -10 0 1 2 3 4 5 6 7 8 8
> -12 0 1 2 2 3 4 5 6 7 8
> -14 0 1 1 2 2 3 4 4 6 7
> -16 0 0 1 1 2 2 3 3 4 4
> -18 0 0 0 1 1 1 1 1 3 3
< -18 0 0 0 0 0 0 0 0 0 0

signalQualityDetails is a collection of the key values relating to signal quality that may aid with troubleshooting. At present, this returns the raw RSRQ, RSRP and RSSI values reported by the device. This may expand in future to include other details. Under normal conditions, signalQuality should be used.

signalQualityLabel provides a ‘human-friendly’ label that maps the 0–9 scale to a commonly used 5 point set of labels, using the following scale:

signalQuality signalQualityLabel
-1 Invalid or Unknown
0, 1, 2 Poor
3, 4 Low
5, 6, 7 Good
8, 9 Excellent

Note that comms.networkId and comms.cellular.carrier are synonyms when the device was last heard via cellular.

comms.wifi

Similarly to the comms.cellular object, a comms.wifi object is returned at all times:

{
  ...
  "comms": {
    ...as outlined above..
    "wifi": {
      "ipAddress": "192.168.20.12",
      "gateway": "192.168.20.1",
      "lastHeardAt": 1710914272,
      "macAddress": "c0:49:ef:03:62:60",
      "mode": "STA",
      "pskUpdatedAt": 1710614272,
      "signalQuality": 4,
      "signalQualityDetail": {
        "rssi": -43
      },
      "signalQualityLabel": "Good",
      "ssid": "My SSID",
      "subnetMask": "255.255.255.0"
    }
    ...
  },
  ...
}

The wifi sub-object lists all of the last known properties relating to the WiFi transport, regardless of which one is currently active (as per the cellular sub-object outlined above). i.e. if a device last communicated via cellular, this object would still be returned in its entirety. This is different to the comms-level properties, which are transient depending on the active transport.

This collection is extensively revised, providing a lot more information than 6W devices.

ipAddress is the IP address assigned to the device when it was last connected to WiFi. Similarly, gateway and subnetMask were the values assigned to the device when last connected.

These values are not currently editable (i.e. they must be assigned by the router the device is connecting to), but may be opened up in the future for custom configuration (e.g. in non-DHCP environments, where a fixed IP needs to be set, or where custom subnet masks are required).

mode represents the WiFi mode that the WiFi sub-system is currently operating in. Presently, only STA (Station) is supported. However, we may introduce AP (Access Point) and other modes in the future.

pskUpdatedAt represents the last time the PSK (Pre-Shared Key, sometimes referred to as password) was updated. For security reasons, we don’t report back the actual PSK stored on the device, so this value acts as a proxy for handling pending state for the PSK value (more on this later).

signalQuality normalises the 10-point scale provided in comms.cellular.signalQuality for WiFi devices. It provides a value between 0 and 9 representing the reported signal quality, based on the RSSI value reported by the WiFi module, based on the following scale:

RSSI signalQuality
Unknown or invalid -1
-91 or below 0
-90 to -81 1
-80 to -76 2
-75 to -71 3
-70 to -66 4
-65 to -61 5
-60 to -56 6
-55 to -51 7
-50 to -41 8
-40 to -30 9

Note that 'Invalid' will also be returned if RSSI is > -30.

signalQualityDetails provides the raw RSSI value. This may be extended in the future to other WiFi properties that are appropriate for troubleshooting WiFi performance.

signalQualityLabel follows the same pattern as for cellular:

signalQuality signalQualityLabel
-1 Invalid or Unknown
0, 1, 2 Poor
3, 4 Low
5, 6, 7 Good
8, 9 Excellent

comms.wifi.ssid is a synonym for comms.networkId when WiFi is the active transport.

Changing WiFi credentials

Previously, all comms values were read-only via the API, as configuration could only be done in proximity to the device (accessed via a device-specific WiFi Access Point).

With the 6MW and 6MW-CER, WiFi credentials (SSID and PSK) can be set via the API.

The method of making these changes follows the pattern established for other read-write values for the device via the API for firmware version 0.13.1 or later.

SSID

To change the SSID, issue a request to PATCH /devices/{device-id} endpoint, with the changed details:

{
  "comms": {
    "wifi": {
      "ssid": "My new SSID"
    }
  }
}

The response from the API will include the full status object, with SSID marked as ‘pending’:

{
  ...
  "comms": {
    "wifi": {
      ...
      "ssid": "My old SSID",
      "pending": {
        "ssid": "My new SSID"
      },
      ...
    }
  },
  ...
}

The ‘pending’ state will remain active until the device has accepted the change and reported an updated status accordingly. At this point, the ssid value will reflect the newly applied configuration:

{
  ...
  "comms": {
    ...
    "wifi": {
      ...
      "ssid": "My new SSID",
      ...
    }
    ...
  },
  ...
}

PSK

For security reasons, the device does not transmit the PSK, nor do we store it within Mercury.

Instead, we use a last-changed timestamp as a proxy. Easiest to illustrate this in practice…

To change the PSK, issue a request to PATCH /devices/{device-id} passing the updated details:

{
  ...
  "comms": {
    ...
    "wifi": {
      ...
      "psk": "My new Password",
      ...
    }
    ...
  },
  ...
}

Instead of returning the PSK that was provided in the request, the API returns a ‘pending’ state for pskUpdatedAt.

When a device has never had a PSK previously, the comms.wifi.pskUpdatedAt value will be null. After it has been set at least once, this value will be a timestamp representing when the PSK was last updated. This will occur even if you update the PSK to the same value as before (also for security reasons).

{
  ...
  "comms": {
    ...
    "wifi": {
      ...
      "pskUpdatedAt": null,
      "pending": {
        "pskUpdatedAt": 1712033637
      }
      ...
    }
    ...
  },
  ...
}

Once the device has applied the change, it will issue an updated status, and the API will lose the pending status:

{
  ...
  "comms": {
    ...
    "wifi": {
      ...
      "pskUpdatedAt": 1712033637,
      ...
    },
    ...
  },
  ...
}

Changing both values at once

The API supports changing both SSID and PSK at the same time. To do so, combine the values in the PATCH request, e.g.:

{
  "comms": {
    "wifi": {
      "ssid": "My new SSID",
      "psk": "My new Password"
    }
  }
}

This will then return a pending state for both values in the full status response, e.g.:

{
  ...
  "comms": {
    "wifi": {
      "ssid": "My old SSID",
      "pskUpdatedAt": 1712031637,
      "pending": {
        "ssid": "My new SSID",
        "pskUpdatedAt": 1712033637
      }
    }
  },
  ...
}

Turning off WiFi on the device

If you want to turn off WiFi (i.e. cause the device to drop back to cellular-only operation) after it has been enabled (by adding credentials), you can do so by sending blank credentials.

Set both values to an empty string, e.g.:

{
  "comms": {
    "wifi": {
      "ssid": "",
      "psk": ""
    }
  }
}

The same pending status process will apply until the credentials are applied by the device.

pskUpdatedAt will be the timestamp the change was received by the API (i.e. it won’t return null).

FAQs

Why all the duplicate fields

In our API we strongly endeavour to maintain backwards compatibility so that customers don't have to re-work their API implementations.

We maintain the existing comms object structure for 6MW devices with a view to maintain backwards compatibility even for systems that haven't been explicitly upgraded to support the 6MW-series devices.

We strongly recommend that you use the new comms.cellular and comms.wifi objects for 6MW-series devices.

Does the 6MW support 3G or 5G cellular operation

No. 6MW-series devices are 4G only.

Does the 6MW support 5GHz WiFi connections

No. 6MW-series devices support 2.4GHz networks only.

What WiFi access schemes are supported

[TODO: get from Chris again...]