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; you can create (i.e, install) a device, get or update its information, or delete (i.e, uninstall) it for a user.

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).

Create device

Creating a device means “install Enertalk device on a site”. A device cannot be created (i.e., installed) without a owner site, and there’s no way to move a device from a site to another. You can still re-use a device by uninstalling it from a site and installing on another site.

Endpoints

POST /sites/:siteId/devices

Parameters

name type description
siteId string (required) site identifier
serialNumber string (required) device serial number. Unnecessary for virtual device as it is assigned at the time of creation.
installType number (required) 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 (required) device install purpose
1: site consumption
2: appliance consumption
3: site generation
4: standalone consumption
dataPeriod number (required) data upload period. Possible values are 1, 10, 30, 60, 300, or 900 (seconds).
dataCount number (required) number of data points uploaded every period. Possible values are 1, 10 or 15 (Hz).
ctCapacities number[] (required) 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)
name string device name
channelCount number device channel count. Applicable for multi-channel device only (installType 5). Default value is 3
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
provider string device provider name. Required for virtual device only (installType 8).
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)
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.
registrationId string device uuid
options string user defined data value for the device.

Request Example

curl -X POST
  -H "Authorization: Bearer <access_token>"
  -H "Content-Type: application/json"
  -d '{
     "serialNumber": "FFFFFFFF",
     "installType": 1,
     "installPurpose": 1,
     "dataPeriod": 1,
     "dataCount": 1,
     "ctCapacities": [100],
     "powerCapacity": 1000,
     "name": "My Home Device",
     "registrationId": "550E8400-E29b-41D4-A716-4466F3000011",
   }'
   "https://api2.enertalk.com/sites/abcdef12/devices"

Response

Newly created device, or error if invalid parameters provided (such as serial number in use on another device).

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",
  "channelCount": 1,
  "channelPurposes": null,
  "provider": null,
  "virtualDevice": null,
  "networkConfig": {
    "ipMode": "dhcp",
    "ipAddress": null,
    "gateway": null,
    "subnet": null,
    "dns": null,
  },
  "targetMeter": null,
  "options": null,
  "createdAt": 1479190407000,
  "uploadedAt": null
}

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,
}

Replace device

Replacing a device means “install a new device while inheriting data from existing device”. If you simply want to update information without device replacement, please use PATCH /devices/:deviceId API instead.

Endpoints

PUT /devices/:deviceId

Parameters

name type description
deviceId string (required) existing device id
serialNumber string (required) serial number of new device
registrationId string device uuid

Request Example

curl -X PUT
  -H "Authorization: Bearer <access_token>"
  -H "Content-Type: application/json"
  -d '{
    "serialNumber": "FFFFFFF2",
  }'
  "https://api2.enertalk.com/devices/12abcdef"

Response

Replaced device object, or error if invalid parameters (such as serial number already in use).

Response Example

{
  "id": "12abcdef",
  "siteId": "abcdef12",
  "serialNumber": "FFFFFFF2",
  "installType": 1,
  "installPurpose": 1,
  "dataPeriod": 1,
  "dataCount": 1,
  "ctCapacities": [100],
  "powerCapacity": 2000,
  "name": "My Home Device",
  "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,
}

Delete device

Delete a device. Only device owner can delete a device.

Endpoints

DELETE /devices/:deviceId

Parameters

name type description
deviceId string (required) device id

Request Example

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

Response

Deleted device id, or error on failure.

Response Example

{
   "id": "12abcdef"
}