Registration and status of the physical hardware feeding the platform — gateways such as the Glow CAD and GlowStick, sensors such as smart electricity meters, and actuators such as auxiliary load control switches. Also exposes the DCC inventory of a meter point by MPxN or by smart-meter EUI, the resources associated to a meter point, and gateway packet-delivery status.
{
"swagger": "2.0",
"info": {
"description": "API definition for CRUD operations on devices. A device is the physical hardware that can be either: <br></br> <ul> <li>a gateway - makes information available to the Glow Platform. The IHD/CAD and GlowSticks are examples of our gateways.</li> <br></br> <li>a sensor - detects events or changes to its environment and sends information to other devices (smart electricity meter)</li><br></br> <li>an actuator - a controller, given specific predefined commands it can trigger events, change its environment or perform an operation (auxiliary load control switch in an electricity meter)</li><br></br> </ul>",
"version": "1.1.0",
"title": "Device Management System",
"license": {
"name": "Copyright © 2012-26 by Hildebrand Technology Limited"
}
},
"host": "api.glowmarkt.com",
"basePath": "/api/v0-1/",
"tags": [
{
"name": "DeviceType",
"description": ""
},
{
"name": "Device",
"description": ""
}
],
"schemes": [
"https"
],
"paths": {
"/devicetype": {
"post": {
"tags": [
"DeviceType"
],
"summary": "Add a new Device Type",
"description": "create a new Device Type",
"operationId": "deviceType.addDeviceType",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "DeviceType Object",
"required": true,
"schema": {
"$ref": "#/definitions/DeviceTypeReq"
}
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/AddDeviceTypeSucess"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/MissingElementsError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
},
"get": {
"tags": [
"DeviceType"
],
"summary": "Find all device types",
"description": "returns a list of devicetypes",
"operationId": "deviceType.findAll",
"produces": [
"application/json"
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/DeviceType"
}
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/devicetype/{id}": {
"get": {
"tags": [
"DeviceType"
],
"summary": "Find Device Type by ID",
"description": "Returns a single Device Type",
"operationId": "deviceType.findById",
"produces": [
"application/json"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of Device Type to return",
"required": true,
"type": "string"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/DeviceType"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": ""
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device": {
"get": {
"tags": [
"Device"
],
"summary": "Get a user's devices",
"description": "Returns an array of the devices that belong to a user.",
"operationId": "device.findAll",
"parameters": [
{
"name": "tags",
"in": "query",
"required": false,
"type": "string",
"description": "hardwareId of a device"
}
],
"produces": [
"application/json"
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Device"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/missingUserIdError"
}
},
"404": {
"description": "Not Acceptable"
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
},
"post": {
"tags": [
"Device"
],
"summary": "Add a new device",
"description": "create a new device",
"operationId": "device.addDevice",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "Device Object to add to the device system",
"required": true,
"schema": {
"$ref": "#/definitions/DeviceReq"
}
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/AddDeviceSuccess"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/definitions/IncorrectElementsError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device/{id}": {
"get": {
"tags": [
"Device"
],
"summary": "Find device by ID",
"description": "Returns a single device",
"operationId": "device.findById",
"produces": [
"application/json"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of device to return",
"required": true,
"type": "string"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Device"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": ""
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device/resource/{resourceId}": {
"get": {
"tags": [
"Device"
],
"summary": "Find the device that sources a specified resource.",
"description": "Returns a Device, that sources a specified resource.",
"operationId": "device.findByResourceId",
"produces": [
"application/json"
],
"parameters": [
{
"name": "resourceId",
"in": "path",
"description": "Resource ID",
"required": true,
"type": "string"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/Device"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": ""
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device/meter-point/{meterPointNumber}/inventory": {
"get": {
"tags": [
"Device Meter Point DCC inventory"
],
"summary": "Get the DCC inventory of a meter point",
"description": "Returns the DCC inventory",
"operationId": "device.getMeterPointInventory",
"produces": [
"application/json"
],
"parameters": [
{
"name": "meterPointNumber",
"in": "path",
"description": "Meter Point Number",
"required": true,
"type": "string"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/MeterPointInventoryResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": ""
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device/smart-meter/{eui}/inventory": {
"get": {
"tags": [
"Device Meter Point DCC inventory"
],
"summary": "Get the DCC inventory of a meter point by providing an EUI.",
"description": "Returns the DCC inventory",
"operationId": "device.getMeterPointInventoryByEUI",
"produces": [
"application/json"
],
"parameters": [
{
"name": "eui",
"in": "path",
"description": "EUI",
"required": true,
"type": "string"
}
],
"security": [
{
"appKeys": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/MeterPointInventoryResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": ""
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device/meter-point/{meterPointNumber}/resources": {
"get": {
"tags": [
"Device Meter Point DCC inventory"
],
"summary": "Get the resources associated to a meter point",
"description": "Returns the resources that are associated to a meter point",
"operationId": "device.getMeterPointResources",
"produces": [
"application/json"
],
"parameters": [
{
"name": "meterPointNumber",
"in": "path",
"description": "Meter Point Number",
"required": true,
"type": "string"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/MeterPointResourceResponse"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": ""
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device/{id}/status": {
"get": {
"tags": [
"Device"
],
"summary": "This call can be used to see whether a gateway device is sending packets to the Glow Platform (i.e. via WiFi).",
"operationId": "device.getStatusbyDeviceId",
"produces": [
"application/json"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of device to return",
"required": true,
"type": "string"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"found": {
"type": "boolean",
"example": true
},
"deviceId": {
"type": "string",
"example": "55c883e0-701e-4810-acf1-e827dbd83fb0"
},
"hardwareId": {
"type": "string",
"example": "968YHFEKLQ"
},
"value": {
"type": "number",
"example": 1517317927
}
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/IncorrectElementsError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/device/status": {
"get": {
"tags": [
"Device"
],
"summary": "This call can be used to see whether a gateway device is sending packets to the Glow Platform (i.e. via WiFi).",
"operationId": "device.getStatusbyHardwareId",
"produces": [
"application/json"
],
"parameters": [
{
"name": "tags",
"in": "query",
"required": true,
"type": "string",
"description": "the HardwareId of the device"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"properties": {
"found": {
"type": "boolean",
"example": true
},
"deviceId": {
"type": "string",
"example": "55c883e0-701e-4810-acf1-e827dbd83fb0"
},
"hardwareId": {
"type": "string",
"example": "968YHFEKLQ"
},
"value": {
"type": "number",
"example": 1517317927
}
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/definitions/IncorrectElementsError"
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
},
"/discover/{hardwareId}": {
"get": {
"tags": [
"discover"
],
"summary": "Find device by ID",
"description": "Returns the devices and if they do not exist the assets and product types",
"operationId": "discoverDevicesAssets",
"produces": [
"application/json"
],
"parameters": [
{
"name": "hardwareId",
"in": "path",
"description": "A hardware identifier of a Device. For a network device, we typically use the MAC address.",
"required": true,
"type": "string"
}
],
"security": [
{
"userToken": [],
"applicationId": []
},
{
"appKeys": [],
"userId": []
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": ""
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": ""
}
},
"500": {
"description": "Internal Server Error",
"schema": {
"$ref": "#/definitions/ServerError"
}
}
}
}
}
},
"securityDefinitions": {
"orgAppKeys": {
"type": "basic"
},
"appKeys": {
"type": "basic"
},
"devUserToken": {
"type": "apiKey",
"name": "token",
"in": "header"
},
"userToken": {
"type": "apiKey",
"name": "token",
"in": "header"
},
"applicationId": {
"type": "apiKey",
"name": "applicationId",
"in": "header"
},
"userId": {
"type": "apiKey",
"name": "userId",
"in": "header"
}
},
"definitions": {
"MeterPointInventory": {
"type": "object",
"properties": {
"DateCommissioned": {
"type": "string",
"example": "2022-02-02T00:00:00.000Z"
},
"DeviceFirmwareVersion": {
"type": "string",
"example": "111"
},
"DeviceManufacturer": {
"type": "string",
"example": "METER_MANUFACTURER"
},
"DeviceModel": {
"type": "string",
"example": 333333
},
"DeviceType": {
"type": "string",
"example": "CHF"
},
"DeviceStatus": {
"type": "string",
"example": "Commissioned"
},
"EUI": {
"type": "string",
"example": "AB123456789012"
},
"ImportMPxN": {
"type": "string",
"example": 123456789012
},
"SmetsVersion": {
"type": "string",
"example": 2
}
}
},
"MeterPointInventoryResponse": {
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"inventory": {
"type": "array",
"items": {
"$ref": "#/definitions/MeterPointInventory"
}
}
}
},
"MeterPointResourceResponse": {
"type": "object",
"properties": {
"valid": {
"type": "boolean",
"example": true
},
"mpxn": {
"type": "string",
"example": 123456789012
},
"resources": {
"type": "array",
"items": {
"$ref": "#/definitions/ResourceListingWithClassifier"
}
}
}
},
"ProtocolResourceType": {
"type": "object",
"properties": {
"protocolId": {
"type": "string"
},
"resourceTypeId": {
"type": "string"
}
},
"required": [
"protocolId",
"resourceTypeId"
]
},
"ProtocolResourceTypeResource": {
"type": "object",
"properties": {
"protocolId": {
"type": "string"
},
"resourceTypeId": {
"type": "string"
},
"resourceId": {
"type": "string"
}
},
"required": [
"protocolId",
"resourceTypeId",
"resourceId"
]
},
"DeviceTypeReq": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"protocol": {
"type": "object",
"properties": {
"sensors": {
"type": "array",
"items": {
"$ref": "#/definitions/ProtocolResourceType"
}
},
"protocol": {
"type": "string"
}
},
"required": [
"protocol",
"sensors"
]
}
}
},
"DeviceReq": {
"type": "object",
"properties": {
"deviceTypeId": {
"type": "string"
},
"hardwareId": {
"type": "string"
},
"hardwareIds": {
"type": "object"
}
},
"required": [
"deviceTypeId",
"hardwareId",
"hardwareIds"
]
},
"ParentHardwareIds": {
"type": "string",
"example": "KO17321203"
},
"DeviceType": {
"type": "object",
"properties": {
"deviceTypeId": {
"type": "string"
},
"description": {
"type": "string"
},
"protocol": {
"type": "object",
"properties": {
"sensors": {
"type": "array",
"items": {
"$ref": "#/definitions/ProtocolResourceTypeResource"
}
},
"protocol": {
"type": "string"
}
},
"required": [
"protocol",
"sensors"
]
}
}
},
"Device": {
"type": "object",
"properties": {
"deviceId": {
"type": "string",
"example": "55c883e0-701e-4810-acf1-e827dbd83fb0"
},
"deviceTypeId": {
"type": "string"
},
"ownerId": {
"type": "string"
},
"description": {
"type": "string"
},
"hardwareId": {
"type": "string",
"example": "60001"
},
"hardwareIds": {
"type": "object",
"example": {
"sid": "60001"
}
},
"parentHardwareId": {
"type": "array",
"items": {
"$ref": "#/definitions/ParentHardwareIds"
}
},
"protocol": {
"type": "object",
"properties": {
"sensors": {
"type": "array",
"items": {
"$ref": "#/definitions/ProtocolResourceTypeResource"
}
},
"protocol": {
"type": "string"
}
},
"required": [
"protocol",
"sensors"
]
}
},
"required": [
"ownerId",
"hardwareId"
]
},
"ResourceListingWithClassifier": {
"type": "object",
"properties": {
"resourceId": {
"type": "string",
"example": "8f2a0722-3b59-47a6-a115-d43fcc0c5d1c"
},
"resourceTypeId": {
"type": "string",
"example": "f8e6fb07-6307-4e0e-8a17-4b94bc7249c2"
},
"classifier": {
"type": "string",
"example": "electricity.consumption"
}
},
"xml": {
"name": "ResourceListingWithClassifier"
}
},
"ServerError": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "An error has occurred"
}
},
"xml": {
"name": "AddResourceError"
}
},
"AddDeviceTypeSucess": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "OK"
},
"deviceTypeId": {
"type": "string",
"example": "a0872822-c10c-4a90-bf8a-17310ffe10af"
}
}
},
"missingUserIdError": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "missing elements -userId"
}
}
},
"AddDeviceSuccess": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "OK"
},
"valid": {
"type": "boolean"
},
"deviceId": {
"type": "string",
"example": "d3vb0129-8c95-43f3-bde2-744007221oli"
}
}
},
"IncorrectElementsError": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "incorrect elements"
}
}
},
"MissingElementsError": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "missing elements"
}
}
}
}
}