Device object represents an Enertalk device (which measures energy usage and upload usage data to Enertalk server), and devices API allows you to manage them.

The device object

name type description
id string device identifier
siteId string site id where device belongs to
serialNumber string device serial number
name string device name
registrationId string device registration id
installType number device install type
1: single-phase two-wires
2: single-phase three-wires
3: poly-phase three-wires
4: poly-phase four-wires
5: multi-channel
6: modem
7: plug
8: virtual device
installPurpose number device install purpose
1: site consumption
2: appliance consumption
3: site generation
4: standalone consumption
5: hybrid
dataPeriod number data upload period. Possible values are 1, 10, 30, 60, 300, or 900 (seconds).
dataCount number number of data points uploaded every period. Possible values are 1, 10 or 15 (Hz).
ctCapacities number[] list of CT capacities for each channel. Possible values are 0, 50, 100, 200, 300, or 600 (A). Use 0 for unknown CT capacity.
powerCapacity number device power capacity (W)
channelCount number device channel count. Applicable for multi-channel device only (installType 5). Default value is 3.
channelPurposes number[] channel purposes. Possible values for each item
1: site consumption
2: appliance consumption
3: site generation
or null for unused channel.
provider string device provider name. Required for virtual device only (installType 8).
virtualDevice object virtual device information. Applicable for virtual device from remote server.
targetMeter object target meter information. Required for modem device only (installType 6).
networkConfig object device network configuration. Applicable for modem device (installType 6) which uses wired Ethernet connection.
options string user defined data value for the device.
createdAt timestamp device creation time
uploadedAt timestamp last upload time for usage data

The VirtualDevice object

name type description
virtualDeviceId string virtual device identifier for remote server (e.g., apartment number)
virtualDeviceGroupId string virtual device group identifier (e.g., apartment id)
ownerId string virtual device owner identifier (e.g., phone number)
action string action taken on device: register or unregister
status string status of device action: standby, ready, done, error
error.code number error code from device action if error happens
error.message string error message for the error code
updatedAt timestamp virtual device status update time

VirtualDevice Errors

code message description
1401 Device registration rejected Corresponds with HTTP 401 error. Device authentication failed.
1404 Device not found Corresponds with HTTP 404 error. Device not found.
1500 Unknown error Corresponds with HTTP 500 error. Device is in error status for unknown reason.

VirtualDevice Example

{
  "virtualDeviceId": "102-304",
  "virtualDeviceGroupId": "a1234567",
  "ownerId": "01011112222",
  "action": "register",
  "status": "error",
  "error": {
    "code": 1401,
    "message": "Device registration rejected"
  },
  "updatedAt": 1479190407000
}

The NetworkConfig object

name type description
ipMode string network ip mode. Possible values are dhcp and static
subnet string subnet mask
gateway string gateway
ipAddress string ip address of device
dns string domain name server

The TargetMeter object

name type description
voltage number voltage of target meter (mV)
pulse number pulse of target meter (pulse/kWh)
ctRatio number current transformation ratio. denominator value. (positive integer)
ptRatio number power transformation ratio. denominator value. (positive integer)

Notes

  • For multi-channel device (installType 5)
    • installPurpose must be 2 (to meter appliance consumption) or 5 (hybrid device).
  • For modem device (installType 6)
    • targetMeter is required.
  • For virtual device (installType 8)
    • provider is required with one of pre-registered providers’ name.
    • serialNumber should be omitted. It is auto-generated from the server.
  • For standalone device (installPurpose 4)
    • Its usage does not count toward site usage.
    • Its bill is calculated on its own (whereas non-standalone device is calculated as part of site bill.)
  • For hybrid device (installPurpose 5)
    • channelCount and channelPurposes are required when creating a device.
    • channelPurposes parameter is ignored for other device types.
  • In general, dataCount is usually 1 (i.e., single data point for each upload).
    • dataCount of 10 or 15 (Hz) allowed only if dataPeriod = 1 (second) and installPurpose != 2 (appliance consumption).

List devices of a site

List all devices belonging to a site.

Endpoints

GET /sites/:siteId/devices

Parameters

name type description
siteId string (required) site identifier

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  "https://api2.enertalk.com/sites/abcdef12/devices"

Response

List of devices object on success, or error on failure.

Response Example

[
   {
     "id": "12abcdef",
     "siteId": "abcdef12",
     "serialNumber": "FFFFFFFF",
     "installType": 1,
     "installPurpose": 1,
     "dataPeriod": 1,
     "dataCount": 1,
     "ctCapacities": [100],
     "powerCapacity": 1000,
     "name": "My Home Device",
     "registrationId": "550E8400-E29b-41D4-A716-4466F3000011",
     "createdAt": 1479190407000,
     "uploadedAt": 1489190407132,
     "channelCount": 1,
     "channelPurposes": null,
     "provider": null,
     "virtualDevice": null,
     "networkConfig": {
       "ipMode": "dhcp",
       "ipAddress": null,
       "gateway": null,
       "subnet": null,
       "dns": null,
     },
     "targetMeter": null,
     "options": null,
   }
]

Get device

Retrieve device information. If authenticated user does not own the device, forbidden error will be returned.

Endpoints

GET /devices/:deviceId

Parameters

name type description
deviceId string (required) device id

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  "https://api2.enertalk.com/devices/12abcdef"

Response

Retrieved device object on success, or error on failure.

Response Example

{
  "id": "12abcdef",
  "siteId": "abcdef12",
  "serialNumber": "FFFFFFFF",
  "installType": 1,
  "installPurpose": 1,
  "dataPeriod": 1,
  "dataCount": 1,
  "ctCapacities": [100],
  "powerCapacity": 1000,
  "name": "My Home Device",
  "registrationId": "550E8400-E29b-41D4-A716-4466F3000011",
  "createdAt": 1479190407000,
  "uploadedAt": 1489190407132,
  "channelCount": 1,
  "channelPurposes": null,
  "provider": null,
  "virtualDevice": null,
  "networkConfig": {
    "ipMode": "dhcp",
    "ipAddress": null,
    "gateway": null,
    "subnet": null,
    "dns": null,
  },
  "targetMeter": null,
  "options": null,
}

Update device

Update device information. If user does not own a device, forbidden error will be returned. Note that you are not allowed update serialNumber or registrationId for which ‘Replace device API’ can be used.

Endpoints

PATCH /devices/:deviceId

Parameters

name type description
deviceId string (required) device id
installPurpose number device install purpose. Allowed to change value from/to
1: site consumption
3: site generation
4: standalone consumption
dataPeriod number data upload period. Possible values are 1, 10, 30, 60, 300, or 900 (seconds).
dataCount number number of data points uploaded every period. Possible values are 1, 10 or 15 (Hz).
ctCapacities number[] list of CT capacities for each channel. Possible values are 0, 50, 100, 200, 300, or 600 (A). Use 0 for unknown CT capacity.
powerCapacity number device power capacity (W)
targetMeter object target meter information. Required for modem device only (installType 6).
networkConfig object device network configuration. Applicable for modem device (installType 6) which uses wired Ethernet connection.
name string device name
channelPurposes number[] channel purposes. Applicable for hybrid device only (installPurpose 5). Possible values for each item
0: unused
1: site consumption
2: appliance consumption
3: site generation
but note that you can update unused channels only.
options string user defined data value for the device.

Request Example

curl -X PATCH
  -H "Authorization: Bearer <access_token>"
  -H "Content-Type: application/json"
  -d '{
    "installPurpose": 3,
    "dataPeriod": 10,
    "dataCount": 1,
    "ctCapacities": [200],
    "powerCapacity": 2000,
    "name": "Updated Device Name"
  }'
  "https://api2.enertalk.com/devices/12abcdef"

Response

Updated device object, or error on failure.

Response Example

{
  "id": "12abcdef",
  "siteId": "abcdef12",
  "serialNumber": "FFFFFFFF",
  "installType": 1,
  "installPurpose": 3,
  "dataPeriod": 10,
  "dataCount": 1,
  "ctCapacities": [200],
  "powerCapacity": 2000,
  "name": "Updated Device Name",
  "registrationId": "550E8400-E29b-41D4-A716-4466F3000011",
  "createdAt": 1479190407000,
  "uploadedAt": 1489190407000,
  "channelCount": 1,
  "channelPurposes": null,
  "provider": null,
  "virtualDevice": null,
  "networkConfig": {
    "ipMode": "dhcp",
    "ipAddress": null,
    "gateway": null,
    "subnet": null,
    "dns": null,
  },
  "targetMeter": null,
  "options": null,
}