LACE API

Сеть Lace поддерживает несколько типов предметно-ориентированных API, которые возможно использовать при разработке и интеграции различных сервисов.

Список API включает в себя:

Lace Impulse API v1.0

Данный API реализован на основе спецификации JSON-RPC 2.0.

Вызов функций осуществляется по следующему URL: http://lace.io/ru/api

Function

get_values(api_key, device_id[, from_date[, to_date]])

Description

Функция принимает на вход ключ доступа к API, идентификатор устройства и период времени, за котрый необходимо получить значения.

Функция возвращает список JSON-объектов в каждом их которых содержится набор выходных параметров: время измерения, число импульсов и значение контрольного входа.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.
from_date integer UNIX-timestamp начала периода времени, за который необходимо получить значения. Если параметр не задан, то будут возвращены все сохранённые значения.
to_date integer UNIX-timestamp конца периода времени, за который необходимо получить значения. Если параметр не задан, то будут возвращены все значения по настоящий момент времени.

Result

Параметр Тип Описание
time integer UNIX-timestamp измерения.
input_1 integer Число зарегистрированных устройством срабатываний импульсного входа №1. (при варианте подключения устройства — «два импульсных входа»)
input_2 integer Число зарегистрированных устройством срабатываний импульсного входа №2. (при варианте подключения устройства — «два импульсных входа»)
input integer Число зарегистрированных устройством срабатываний импульсного входа. (при варианте подключения устройства — «один импульсный вход и один контрольный вход»)
flag bool Значение контрольного входа (при варианте подключения устройства — «один импульсный вход и один контрольный вход»). Контрольный вход в различных счётчиках используется по-разному, например для детектирования магнитного поля или попытки вскрытия счётчика.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "get_values",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd",
      "from_time": 1431615389,
      "to_time": 1431615405
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": [
      {
         "time": 1431615393,
         "flag": false,
         "input": 1532
      },
      {
         "time": 1431615398,
         "flag": false,
         "input": 1533
      },
      {
         "time": 1431615403,
         "flag": true,
         "input": 1534
      }
   ]
}

Function

get_last_value (api_key, device_id)

Description

Функция принимает на вход ключ доступа к API и идентификатор устройства.

Функция возвращает JSON-объект в котором содержится последний зарегистрированный устройством набор выходных параметров: время измерения, число импульсов и значение контрольного входа.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.

Result

Параметр Тип Описание
time integer UNIX-timestamp измерения.
value integer Число зарегистрированных устройством срабатываний импульсного входа.
flag integer Значение контрольного входа (0,1). Контрольный вход в различных счётчиках используется по-разному, например для детектирования магнитного поля или попытки вскрытия счётчика.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "get_last_data",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd"
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "flag": false,
      "input": 13252,
      "time": 1431674039
   }
}

Lace Lights API v1.0

Данный API реализован на основе спецификации JSON-RPC 2.0.

Вызов функций осуществляется по следующему URL: http://lace.io/ru/api

Function

get_state (api_key, device_id)

Description

Функция принимает на вход ключ доступа к API и идентификатор устройства.

Функция возвращает JSON-объект в котором содержится состояние устройства: время последнего изменения состояния, уровень освещения и сила тока.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.

Result

Параметр Тип Описание
time integer UNIX-timestamp измерения.
power float Уровень освещения в процентах.
current float Значение силы тока в амперах.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "get_state",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd"
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "flag": 0,
      "current": 0.536,
      "power": 52.5
   }
}

Function

set_state (api_key, device_id, power)

Description

Функция принимает на вход ключ доступа к API, идентификатор устройства и уровень освещения, который планируется выставить.

Функция возвращает «ok» в случае успешной запланированной отправки.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.
power float Уровень освещения в процентах.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "get_state",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd",
      "power": 52.5
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": "ok"
}

Lace Tracking API v1.0

Данный API реализован на основе спецификации JSON-RPC 2.0.

Вызов функций осуществляется по следующему URL: http://lace.io/ru/api

Function

get_track(api_key, device_id[, from_date[, to_date]])

Description

Функция принимает на вход ключ доступа к API, идентификатор устройства и период времени, за котрый необходимо получить значения.

Функция возвращает список JSON-объектов в каждом их которых содержится набор выходных параметров: время измерения, координаты, скорость, направление и время по GPS.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.
from_date integer UNIX-timestamp начала периода времени, за который необходимо получить значения. Если параметр не задан, то будут возвращены все сохранённые значения.
to_date integer UNIX-timestamp конца периода времени, за который необходимо получить значения. Если параметр не задан, то будут возвращены все значения по настоящий момент времени.

Result

Параметр Тип Описание
time integer UNIX-timestamp измерения.
latitude float Широта по показаниям GPS.
longitude float Долгота по показаниям GPS.
altitude float Высота по показаниям GPS.
precision float Точность по показаниям GPS.
velocity float Скорость движения по показаниям GPS.
direction float Направление движения по показаниям GPS.
gps_time double UNIX-timestamp измерения по показаниям GPS.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "get_track",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd",
      "from_time": 1432654811,
      "to_time": 1432654816
   }
}

Response

{
   "id": 1,
   "jsonrpc": "2.0",
   "result": [
      {
         "altitude": 16.8,
         "direction": -16.5,
         "gps_time": 1432665611.397664,
         "latitude": 60.639406666666666,
         "longitude": 23.24243166666667,
         "precision": 10,
         "time": 1432654811,
         "velocity": -0.6733
      },
      {
         "altitude": 16.9,
         "direction": -12.8,
         "gps_time": 1432665613.399311,
         "latitude": 60.65103333333333,
         "longitude": 23.138671666666667,
         "precision": 10,
         "time": 1432654813,
         "velocity": -0.6265
      },
      {
         "altitude": 17,
         "direction": -17.4,
         "gps_time": 1432665615.400793,
         "latitude": 60.66659833333333,
         "longitude": 23.037,
         "precision": 10,
         "time": 1432654815,
         "velocity": -0.6171
      }
   ]
}

Function

get_position (api_key, device_id)

Description

Функция принимает на вход ключ доступа к API и идентификатор устройства.

Функция возвращает JSON-объект в котором содержится последний зарегистрированный устройством набор выходных параметров: время измерения, координаты, скорость, направление и время по GPS.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.

Result

Параметр Тип Описание
time integer UNIX-timestamp измерения.
latitude float Широта по показаниям GPS.
longitude float Долгота по показаниям GPS.
altitude float Высота по показаниям GPS.
precision float Точность по показаниям GPS.
velocity float Скорость движения по показаниям GPS.
direction float Направление движения по показаниям GPS.
gps_time double UNIX-timestamp измерения по показаниям GPS.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "get_position",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd"
   }
}

Response

{
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
      "altitude": 13.5,
      "direction": -34.4,
      "gps_time": 1432665487.297912,
      "latitude": 59.98488833333333,
      "longitude": 29.320401666666665,
      "precision": 10,
      "time": 1432654687,
      "velocity": -0.198
   }
}

Function

set_update_period (api_key, device_id, seconds)

Description

Функция принимает на вход ключ доступа к API, идентификатор устройства и период обновления показаний в секундах.

Функция возвращает «ok» в случае успешно запланированной отправки.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.
seconds integer Период отправки показаний в секундах.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "set_update_period",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd",
      "seconds": 600
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": "ok"
}

Function

get_battery (api_key, device_id)

Description

Функция принимает на вход ключ доступа к API и идентификатор устройства.

Функция возвращает JSON-объект в котором содержится последнее зарегистрированное состояние батареи устройства.

Parameters

Параметр Тип Описание
api_key string Ключ доступа к API, который можно получить в web-интерфейсе. При перегенерации ключа, старый перестаёт действовать.
device_id string Идентификатор устройства в шестнадцатиричном формате. Данный идентификтор нанесён на корпус устройства.

Result

Параметр Тип Описание
time integer UNIX-timestamp измерения.
level float Уровень батареи в процентах

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "get_battery",
   "id": 1,
   "params": {
      "api_key": "ecc1e2764f94686ba098199cec03cf92",
      "device_id": "aabbccddaabbccdd"
   }
}

Response

{
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
      "level": 90.0,
      "time": 1432654687
   }
}

Lace Сore API

Данный API реализован на основе спецификации JSON-RPC 2.0 и спецификации  LoRaWAN.

Вызов функций осуществляется на callback_url, указанный в аккаунте клиента.

Function

check(dev_uid)

Description

Функция принимает на вход идентификатор устройства.

Функция должна вернуть статус проверки принадлежности устройства «ok» или «error».

Parameters

Параметр Тип Описание
dev_uid string Идентификатор устройства в шестнадцатиричном формате.

Result

Параметр Тип Описание
result string «ok» если устройство известно клиенту и может быть зарегистрировано, «error» в противном случае.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "check",
   "id": 1,
   "params": {
      "dev_uid": "aabbccddaabbccdd"
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": "ok"
}

Function

register(dev_uid, net_id, dev_nonce, dev_addr)

Description

Функция принимает на вход идентификатор устройства, идентификатор сети, случайный токен, сгенерированный устройством, новый сетевой адрес устройства и список каналов.

Функция должна вернуть сгенерированный сетевой ключ шифрования и зашифрованный ответный пакет.

Генерация ключей шифрования и ответного пакета описаны в спецификации по LoRaWAN[1], раздел 6.2.5.

Parameters

Параметр Тип Описание
dev_uid string Идентификатор устройства в шестнадцатиричном формате.
net_id string Идентификатор сети в шестнадцатиричном формате.
dev_nonce string Случайный токен в шестнадцатиричном формате. Используется только для регистрации устройства.
dev_addr string Сетевой адрес устройства в шестнадцатиричном формате.
cf_list string Список каналов в шестнадцатиричном формате. Может отсутствовать.

Result

Параметр Тип Описание
net_skey string Сетевой ключ шифрования в шестнадцатиричном формате.
accept_payload string Зашифрованный ответный пакет, представленный в BASE64.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "method": "register",
   "id": 1,
   "params": {
      "dev_uid": "0505050505050505",
      "net_id": "000000",
      "dev_nonce": "0102",
      "dev_addr": "0a1b2c3d"
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "net_skey": "d64c9050214b394aa2042f0e934b6180",
      "accept_payload": "ysgRl452xNLep9S1NTIg2lomKDxUgn3DJ7DE+b00Ass"
   }
}

Function

message(dev_addr, rx_time, counter_up, counter_down, data)

Description

Функция принимает на вход сетевой адрес устройства, время приёма пакета, счётчик пакетов от устройства, счётчик пакетов на устройство и пришедшие данные.

Функция может вернуть данные, которые требуется отправить на устройство, значение счётчика пакетов на устройство, с которым произведено шифрование данных и флаг, указывающий на наличие ожидающих отправки данных. В случае, если данных для отправки нет, необходимо вернуть пустой JSON-объект.

Процесс шифрования данных описан в спецификации по LoRaWAN[1], раздел 4.3.3.

Parameters

Параметр Тип Описание
dev_addr string Сетевой адрес устройства в шестнадцатиричном формате.
rx_time float UNIX-timestamp прихода пакета.
counter_up integer Значение счётчика пакетов от устройства из полученного пакета.
counter_down integer Ожидаемое значение счётчика пакетов на устройство для следующего отправленного пакета. Может быть изменено клиентом.
data JSON объект Структура данных, полученных от устройства. Равно null, если пакет пришел без данных.
data.port string Порт данных — параметр, значение которого обрабатывается сервером приложений по своему усмотрению. К примеру, данный параметр может быть использован для разных потоков данных с одного устройства.
data.payload string Данные от устройства, зашифрованные с помощью AppSKey, представленные в BASE64.

Result

Параметр Тип Описание
pending boolean Флаг наличия ожидающих отправки данных.
counter_down integer Принудительно выставленное значение счётчика пакетов на устройство для данного пакета. Может отсутствовать
data JSON объект Структура данных, . Может отсутствовать, если нет данных на отправку.
data.port string Порт данных — параметр, значение которого обрабатывается сервером приложений по своему усмотрению. К примеру, данный параметр может быть использован для разных потоков данных с одного устройства.
data.payload string Данные на устройство, зашифрованные с помощью AppSKey, представленные в BASE64.

Example

В данном примере приведён запрос и ответ, включающий в себя служебные данные JSON-RPC.

Request

{
   "jsonrpc": "2.0",
   "id": 1,
   "method": "message",
   "params": {
      "dev_addr": "0a1b2c3d",
      "rx_time": 1432039317.182315,
      "counter_up": 10,
      "counter_down": 100,
      "data": {
         "port": 2,
         "payload": "DS4CGaDCdG+48eJNM3Vai-zDpsR71Pn9CPA9uCON84"
      }
   }
}

Response

{
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
      "pending": true,
      "counter_down": 100,
      "data": {
         "port": 2,
         "payload": "DS4CGaDCdG+48eJNM3Vai-zDpsR71Pn9CPA9uCON84"
      }
   }
}

References

[1] LoRaWAN Specification http://lora-alliance.org/For-Developers/LoRaWANDevelopers