NAV Navbar
curl python php

Введение

API системы ZONT позволяет получать информацию о состоянии устройств марки ZONT и Mega SX и управлять ими из собственного приложения или сайта. Через API доступны все функции системы, и всё, что вы можете сделать через веб-интерфейс, также доступно и через API. В то же время, эта документация пока не является полной, поэтому если вам потребуются какие-то функции, которые здесь не описаны, то напишите нам, и мы дополним документацию. Также есть упрощённое API для взаимодействия с приборами.

Примеры

# $ pip install requests

import requests

<?php
require_once 'Requests.php';
Requests::register_autoloader();

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

Формат запросов

POST https://my.zont.online/api/set_io_port HTTP/1.1
Host: zont-online.ru
Content-Type: application/json
Content-Length: 88
Authorization: Basic ZWxvbjptYXJzNGV2ZXI=
X-ZONT-Client: elon@tesla.com

{
  "device_id": 1209,
  "portname": "siren",
  "type": "bool",
  "value": true
}

Обращения к API производятся с помощью POST-запросов на адрес https://my.zont.online/api/method, где method — названия метода API. Некоторые методы вызываются с помощью метода GET, это оговаривается отдельно в описании этих методов.

В каждом запросе должен быть указан заголовок X-ZONT-Client. Укажите в этом заголовке ваш e-mail или иной контакт, по которому мы сможем связаться с вами в случае планируемых изменений в API.

Параметры запроса передаются одним из способов:

Результат запроса

{
  "ok": false,
  "error": "no_such_device",
  "error_ui": "Устройство не найдено"
}

Если не оговорено иное, сервер отвечает на запрос результатом в формате JSON. В возвращаемом объекте всегда присутствует поле "ok", которое равно true в случае успеха или false в случае ошибки. Если поле "ok" равно false, то в ответе также будут присутствовать поля "error" с кодом ошибки и "error_ui" с её описанием на русском языке. "error_ui" может содержать либо строку, либо массив строк если возникло несколько ошибок.

Аутентификация

Большинство запросов к API требуют аутентификации. В данный момент поддерживается два метода аутентификации: с помощью пароля, и с помощью аутентификационного токена.

Предпочтительная схема взаимодействия с API выглядит так:

  1. Получить аутентификационный токен с помощью метода get_authtoken. Этот запрос подтвердить логином и паролем пользователя.
  2. Дальнейшие запросы аутентифицировать полученным токеном, а пароль пользователя больше не использовать и не хранить.
  3. Если запрос к API провалился с кодом 403, то возможно токен был отозван пользователем. В этом случае нужно предложить пользователю снова ввести логин и пароль, получить новый токен с помощью get_authtoken и в дальнешем использовать его.

Аутентификация паролем

curl 'https://my.zont.online/api/get_authtoken' \
  -u 'login:password'                           \
  -H 'X-ZONT-Client: your@email.com'                \
  -H 'Content-Type: application/json'           \
  -d '{"client_name": "My cool app"}'

import requests

result = requests.post(
    'https://my.zont.online/api/get_authtoken',
    auth=('login', 'password'),
    headers={'X-ZONT-Client': 'your@email.com'},
    json={"client_name": "My cool app"}
).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$response = Requests::post(
    'https://my.zont.online/api/get_authtoken',
    ['X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json'],
    json_encode(['client_name' => 'My cool app']),
    ['auth' => ['login', 'password']]
);

Не забудьте заменить login, password на логин и пароль пользователя, your@email.com на email разработчика, а "My cool app" — на название вашего приложения

Просто укажите логин и пароль пользователя с помощью HTTP Basic Authentication. Это можно сделать либо встроенными средствами вашей http-библиотеки, либо указав заголовок:

Authorization: Basic XXX

где XXX — это строка логин:пароль, закодированная в Base64.

Аутентификация с помощью токена

curl 'https://my.zont.online/api/some_method' \
  -H 'X-ZONT-Client: your@email.com'              \
  -H 'X-ZONT-Token: xxxxxxxxxxxxxxxxxx'

import requests

result = requests.post(
    'https://my.zont.online/api/some_method',
    headers={'X-ZONT-Client': 'your@email.com',
             'X-ZONT-Token': 'xxxxxxxxx'}
).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$response = Requests::post(
    'https://my.zont.online/api/some_method',
    ['X-ZONT-Client' => 'your@email.com', 'X-ZONT-Token': 'xxxxxxxx']
);

Укажите аутентификационный токен в заголовке X-ZONT-Token.

Метод get_authtoken — Получение аутентификационного токена

curl 'https://my.zont.online/api/get_authtoken' \
  -u 'login:password'                           \
  -H 'X-ZONT-Client: your@email.com'                \
  -H 'Content-Type: application/json'           \
  -d '{"client_name": "My cool app"}'

import requests

result = requests.post(
    'https://my.zont.online/api/get_authtoken',
    auth=('login', 'password'),
    headers={'X-ZONT-Client': 'your@email.com'},
    json={"client_name": "My cool app"}
).json()

token = result['token']

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$response = Requests::post(
    'https://my.zont.online/api/get_authtoken',
    ['X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json'],
    json_encode(['client_name' => 'My cool app']),
    ['auth' => ['login', 'password']]
);

$token = json_decode($response->body)->token;

POST https://my.zont.online/api/get_authtoken

Возвращает аутентификационный токен для использования в дальнейшем для запросов от имени указанного пользователя.

Этот метод должен отправляться с аутентификацией по паролю.

Параметры

Имя Тип Описание
client_name string человекопонятное название вашего приложения

Результат

В поле token будет строка — аутентификационный токен, который нужно указывать в заголовке X-ZONT-Token в последующих запросах.

Устройства

devices — Запрос устройств

curl 'https://my.zont.online/api/devices' \
  -u 'demo:demo'                          \
  -H 'X-ZONT-Client: your@email.com'          \
  -H 'Content-Type: application/json'     \
  -d '{"load_io": true}'

import requests

url = 'https://my.zont.online/api/devices'
data = {'load_io': True}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/devices';
$data = array('load_io' => true);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "ok": true,
  "devices": [
    {
      "device_id": 1209
      ...
    }
  ]
}

POST https://my.zont.online/api/devices

Возвращает список всех устройств пользователя, а также их параметров.

Параметры

Имя Тип Описание
load_io bool возвращать ли в поле io Состояния устройства (см. Параметры устройств)

Результат

В поле devices возвращается массив объектов, описывающих устройства. Порядок элементво в массиве соответствует порядку устройств в личном кабинете пользователя.

Каждый объект, описывающий устройство, может иметь поля, описанные в разделе Параметры устройств.

add_device — Добавить устройство

curl 'https://my.zont.online/api/add_device'                                            \
  -u 'demo:demo'                                                                        \
  -H 'X-ZONT-Client: your@email.com'                                                        \
  -H 'Content-Type: application/json'                                                   \
  -d '{"devtype": "ZTC-700", "name": "my car", "serial": "012345678915", "timezone": 3}'

import requests

url = 'https://my.zont.online/api/add_device'
data = {
    'devtype': 'ZTC-700',
    'name': 'my car',
    'serial': '012345678915',
    'timezone': 3
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/add_device';
$data = array(
    'devtype' => "ZTC-700",
    'name' => "my car",
    'serial' => "012345678915",
    'timezone' => 3
);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "ok": true,
  "device_id": 1209
}

POST https://my.zont.online/api/add_device

Добавить устройство в аккаунт пользователя.

Параметры

Имя Тип Обязательный Описание
devtype string да Тип устройства. Один из идентификаторов, описанных в разделе Типы устройств.
name string да Название устройства для пользователя.
serial string да Серийный номер
timezone int да Часовой пояс
tel_password string нет Телефонный пароль (для GSM-устройств). Телефонный пароль запрашивается устройством при дозвоне на него с номера, не являющегося доверенным. Строка должна состоять только из цифр.
notes string нет Произвольные заметки об устройстве (например, номер его SIM-карты, чтобы не забыть)
wifi_credentials array нет Параметры Wi-Fi-сети (только для устройств с Wi-Fi). Массив объектов вида {"ssid": "имя_сети", "password": "пароль_сети"}. ZONT H-2 поддерживает не более одной сети.
boiler_vendor string нет Производитель котла (для отопительных устройств)
boiler_model string нет Модель котла (для отопительных устройств)

Результат

Возвращается объект с полем device_id равным ID нового устройства.

delete_device — Удалить устройство

curl 'https://my.zont.online/api/delete_device' \
  -u 'demo:demo'                                \
  -H 'X-ZONT-Client: your@email.com'                \
  -H 'Content-Type: application/json'           \
  -d '{"device_id": 1209, "clear_data": true}'

import requests

url = 'https://my.zont.online/api/delete_device'
data = {
    'device_id': 1209,
    'clear_data': True
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/delete_device';
$data = array(
    'device_id' => 1209,
    'clear_data' => true
);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "ok": true
}

POST https://my.zont.online/api/delete_device

Удалить устройство из аккаунта пользователя.

Параметры

Имя Тип Обязательный Описание
device_id int да ID устройства
transfer bool нет Передать устройство другому пользователю вместо удаления
transfer_username string нет Логин пользователя, которому передать устройство. Применяется только если параметр transfer равен true.
clear_access bool нет Отозвать доступ других пользователей к этому устройству. Если поле transfer не равно true, то доступ других пользователей к устройству отзывается независимо от значения этого параметра.
clear_data bool нет Удалить все накопленные данные по этому устройству

Результат

{"ok": true}

update_device — Изменение настроек устройства

curl 'https://my.zont.online/api/update_device'                      \
  -u 'demo:demo'                                                     \
  -H 'X-ZONT-Client: your@email.com'                                     \
  -H 'Content-Type: application/json'                                \
  -d '{"device_id": 1580, "thermostat_mode_temps": {"comfort": 21}}'

import requests

url = 'https://my.zont.online/api/update_device'
data = {
    'device_id': 1580,
    'thermostat_mode_temps': {
        'comfort': 21
    }
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/update_device';
$data = array(
    'device_id' => 1580,
    'thermostat_mode_temps' => array(
        'comfort' => 21
    )
);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "ok": true,
  "thermostat_mode_temps": {
    "comfort": 21,  // только это поле было изменено
    "econom": 16,
    "idle": 5,
    "full_off": false
  }
}

POST https://my.zont.online/api/update_device

Изменяет параметры устройства. Если устройство на связи, обновлённые параметры будут сразу же отправлены ему. Если связи с устройством в данные момент нет, то настройки будут отправлены при следующем выходе на связь.

Параметры

Имя Тип Описание
device_id int ID устройства

Все остальные параметры в запросе обозначают настройки устройства, которым нужно установить соответствующие значения. Возможные имена, значения и форматы настроек описаны в разделе Параметры устройств.

В случае составного параметра, имеющего внутренние поля, в запросе могут быть указаны только некоторые поля этого параметра. Остальные поля сохранят своё прежнее значение. Так, в примере справа была изменена только целевая температура режима Комфорт, а температуры других режимов остались прежними.

Результат

В возвращаемом объекте указываются все параметры, которые были изменены по запросу, и их новые значения.

set_io_port — Управление состоянием устройства

curl 'https://my.zont.online/api/set_io_port'         \
  -u 'demo:demo'                                      \
  -H 'X-ZONT-Client: your@email.com'                      \
  -H 'Content-Type: application/json'                 \
  -d '{"device_id": 1209, "portname": "guard-state",
       "type": "string", "value": "enabled"}'

import requests

url = 'https://my.zont.online/api/set_io_port'
data = {
    'device_id': 1209,
    'portname': 'guard-state',
    'type': 'string',
    'value': 'enabled'
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/set_io_port';
$data = array(
    'device_id' => 1209,
    'portname' => 'guard-state',
    'type' => 'string',
    'value' => 'enabled'
);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "ok": true
}

POST https://my.zont.online/api/set_io_port

Посылает устройству команду на изменение одного из следующих Состояний:

Отправка команды возможна только тогда, когда устройство на связи. Метод всегда возвращает успешное значение, даже в случае, когда связи с устройством нет или если отправка команды не удалась.

Параметры

Имя Тип Описание
device_id int ID устройства
portname string Имя состояния. Допустима одна из строк: "guard-state", "siren", "engine-block", "webasto" или "auto-ignition"
type string Тип значения. Нужные значения описаны в следующей таблице
value Требуемое значение состояния

Значение параметров type и value:

Имя состояния type value
"guard-state" "string" "enabled" для постановки на охрану, "disabled" для снятия с охраны
"auto-ignition" "auto-ignition" объект с полем state, равным: "enabled" для нормального включения автозапуска, "engine" для запуска только двигателя (без подогревателя), "webasto" для включения только подогревателя, "disabled" для выключения автозапуска, "delay" для продления автозапуска. При использовании state: "delay" также должно быть указано поле time с количеством секунд, до которых нужно продлить автозапуск.
прочие "bool" true для включения или false для выключения соответствующего состояния

Результат

Возвращается объект с единственным полем ok.

send_custom_command — Отправка пользовательской команды

curl 'https://my.zont.online/api/send_custom_command' \
  -u 'demo:demo'                                      \
  -H 'X-ZONT-Client: your@email.com'                      \
  -H 'Content-Type: application/json'                 \
  -d '{"device_id": 18945, "command_id": 1}'

import requests

url = 'https://my.zont.online/api/send_custom_command'
data = {
    'device_id': 18945,
    'command_id': 1
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/send_custom_command';
$data = array(
    'device_id' => 18945,
    'command_id' => 1
);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "ok": true
}

POST https://my.zont.online/api/send_custom_command

Посылает устройству одну из пользовательских команд, которые задаются для ZTC-7xx и Mega SX в настроечной утилите.

Отправка команды возможна только тогда, когда устройство на связи. Метод всегда возвращает успешное значение, даже в случае, когда связи с устройством нет или если отправка команды не удалась.

Параметры

Имя Тип Описание
device_id int ID устройства
command_id int ID команды

Идентификтор команды соответствует полю commands[...].id одного из элементов массива в настройке custom_controls (см. Пользовательские команды и статусы).

Результат

Возвращается объект с одним лишь полем ok.

Загрузка данных

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

load_data — Загрузка различных видов данных

curl 'https://my.zont.online/api/load_data'         \
  -u 'demo:demo'                                    \
  -H 'X-ZONT-Client: your@email.com'                    \
  -H 'Content-Type: application/json'               \
  -d '{"requests": [
        {"device_id": 1580,
         "data_types": ["temperature", "events"],
         "mintime": 1495011600,
         "maxtime": 1495022400},
        {"device_id": 1209,
         "data_types": ["gps", "events"],
         "mintime": 1495011600,
         "maxtime": 1495022400}
      ]}'

import requests

url = 'https://my.zont.online/api/load_data'
data = {
    'requests': [
        {
            'device_id': 1580,
            'data_types': ['temperature', 'events'],
            'mintime': 1495011600,
            'maxtime': 1495022400
        },
        {
            'device_id': 1209,
            'data_types': ['gps', 'events'],
            'mintime': 1495011600,
            'maxtime': 1495022400
        }
    ]
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/load_data';
$data = array(
    'requests' => array(
        array(
            'device_id' => 1580,
            'data_types' => array('temperature', 'events'),
            'mintime' => 1495011600,
            'maxtime' => 1495022400
        ),
        array(
            'device_id' => 1209,
            'data_types' => array('gps', 'events'),
            'mintime' => 1495011600,
            'maxtime' => 1495022400
        )
    )
);
$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "responses": [
    {
      "ok": true,
      "device_id": 1580,
      "temperature": ...,
      "events": ...
    },
    {
      "ok": true,
      "device_id": 1209,
      "gps": ...,
      "events": ...
    }
  ]
}

POST https://my.zont.online/api/load_data

Получить историю показаний датчиков, историю перемещений, событий или любых других данных, которые устройство передало на сервер.

Параметры

Один HTTP-запрос к методу load_data может одновременно загрузить данные разных типов и сразу по нескольким устройствам. Для этого метод принимает параметр requests, который должен быть массивом из объектов-запросов, имеющих следующие поля:

Имя Тип Обязательный Описание
device_id int да ID устройства
data_types array да Список названий типов данных, которые нужно загрузить. Каждый элемент — строка, обозначающая тип данных, например "gps" или "temperature". Список доступных типов данных приведён в разделе Типы сохраняемых данных.
mintime int нет Начало временного диапазона (включительно)
maxtime int нет Конец временного диапазона (включительно)

Временные метки указываются в формате unix time, то есть в виде целого числа секунд, прошедших с 1970-01-01 00:00:00 (UTC).

Результат

Ответ будет содержать поле responses с массивом ответов, соответствующих запросам, переданным в параметре requests в том же порядке.

Каждый ответ содержит поля:

Имя Тип Описание
ok bool Успешно ли обработан запрос
device_id int ID устройства

Кроме того ответ будет содержать поля, совпадающие по названиям с типами данных, указанными в поле data_types запроса. Каждое такое поле в значении будет содержать сами запрошенные данные. Формат этих данных описан в разделе Типы сохраняемых данных.

raw_events — История событий

curl 'https://my.zont.online/api/raw_events'                            \
  -u 'demo:demo'                                                        \
  -H 'X-ZONT-Client: your@email.com'                                        \
  -H 'Content-Type: application/json'                                   \
  -d '{"device_id": 1209, "only": ["GuardOn", "GuardOff"],
       "mintime": 1486252800, "maxtime": 1486339200}'

import requests

url = 'https://my.zont.online/api/raw_events'
data = {
    'device_id': 1209,
    'mintime': 1486252800,
    'maxtime': 1486339200,
    'only': ['GuardOn', 'GuardOff']
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/raw_events';
$data = array(
    'device_id' => 1209,
    'mintime' => 1486252800,
    'maxtime' => 1486339200,
    'only' => array('GuardOn', 'GuardOff')
);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$response = Requests::post($url, $headers, json_encode($data), $options);
$result = json_decode($response->body, true);

Результат:

{
  "ok": true,
  "events": [
    [
      "GuardOn-1486253766",  // id
      1486253766,            // время
      "GuardOn",             // тип
      43.871066,             // долгота
      56.166916,             // широта
      null,                  // продолжительность
      {                      // данные
          "reason": "fob",   //   причина постановки на охрану
          "fob_number": 1    //   номер брелока
      },
      false                  // тревожное?
    ],

    ...
  ]
}

POST https://my.zont.online/api/raw_events

Получить список событий, зарегистрированных устройством в заданном промежутке времени.

Параметры

Имя Тип Обязательный Описание
device_id int да ID устройства
mintime int да Начало временного диапазона (включительно)
maxtime int да Конец временного диапазона (включительно)
only array нет Интересующие типы событий
except array нет Не интересующие типы событий

Время указывается в целых секундах, прошедших с 1970-01-01 00:00:00 (UTC). Не забудьте сделать поправку на нужный часовой пояс!

С помощью параметров only и except можно отфильтровать возвращаемый список событий. Каждый из этих необязательных параметров может содержать массив типов событий (строк). Если указан параметр only, то возвращаются только события типов, указанных в нём. Если указан except, то события типов, указанных в нём, не возвращаются. Если оба парамтера не указаны, возвращаются все события.

Результат

Ответ будет содержать поле events, содержащее массив событий, отсортированных по времени. Каждое событие — это массив, содержащий следующие элементы:

Индекс Тип Описание
0 string Идентификатор события. Мы решили отказаться от уникальных идентификаторов событий, поэтому это поле существует только для совместимости со старыми версиями клиентов и не является в действительности уникальным. Не рекомендуем использовать это поле, оно будет удалено в будущих версиях API.
1 int Время события (в секундах с 1970-01-01 00:00:00 UTC)
2 string Тип события
3 float Долгота местоположения события в градусах (null если неизвестно)
4 float Широта местоположения события в градусах (null если неизвестно)
5 int Длительность события в секундах (null если неизвестно). Указывается только для некоторых типов событий, например "Stop" (остановка).
6 object Дополнительная информация о событии (null если отсутствует). Формат этого поля определяется типом события.
7 bool Является ли событие тревожным («важным»)

Типы событий

Тип Тревожное Описание Доп. данные
"Stop" нет Остановка устройства с GPS. Продолжительность остановки в секундах передаётся не в поле дополнительных данных, а в поле длительности. null
"PowerOn" нет Включение устройства. В поле длительности — время в секундах, в течение которого устройство было выключено. null
"PowerOff" нет Выключение устройства null
"MainPowerLost" да Пропадание основного питания null
"MainPowerFound" да Появление основного питания null
"GPSLost" нет Потеря сигнала GPS null
"GPSFound" нет Нахождение сигнала GPS null
"GSMLost" нет Потеря сигнала GSM null
"GSMFound" нет Регистрация в сети GSM null
"connected" нет Соединение с сервером null
"disconnected" нет Отключение от сервера "reason" — причина отключения (строка)
"reconnected" нет Переподключение к серверу null
"GuardOn" нет Постановка на охрану "reason" — причина постановки:
  • "fob" — брелок
  • "call" — голосовое меню
  • "sms" — СМС
  • "app" — веб-интерфейс или приложение
  • "autoguard" — автопостановка
  • "centrallock" — центральный замок
  • "handsfree" — радиометка
  • "pin" — ПИН-код

"fob_number" — номер брелока
"phonenumber" — номер телефона.
"GuardOff" нет Снятие с охраны (см. "GuardOn")
"AlarmButton" да Нажатие тревожной кнопки null
"Shock1" нет Слабый удар null
"Shock2" да Сильный удар null
"Door" да Тревога по открытию двери null
"Door1", "Door2", "Door3", "Door4", "Door5", "Door6" да Тревога по открытию соответствующей двери null
"HoodTrunk" да Тревога по открытию капота/багажника null
"Hood" да Тревога по открытию капота null
"Trunk" да Тревога по открытию багажника null
"AutoIgnition" нет Автозапуск двигателя "reason" — причина ("manual" — по команде, "temperature" — по температуре, "timer" — по таймеру, "schedule" — по расписанию)
"result" — результат ("success" — успешно, "fail" — неуспешно, "breakdown" — двигатель заглох)
"EngineBreakdown" да Аварийная остановка двигателя null
"SoftwareUpgrade" нет Обновление ПО "firmware_version" — версия прошивки, "profile_version" — версия профиля
"Alarm" да Тревога null
"AlarmIgnition" да Тревога по зажиганию null
"AlarmTilt" да Тревога по датчику наклона null
"AlarmBrake" да Тревога по педали тормоза null
"EngineBlock" да Сработала блокировка двигателя null
"Moving" да Тревога по движению null
"Blackout" да Глушение сигнала GSM null
"GSMLostAlarm" да Тревога по пропаданию сигнала GSM null
"EngineStarted" нет Двигатель заведён null
"EngineStopped" нет Двигатель остановлен null
"DriverCallButton" да Кнопка вызова водителя null
"OutCallTone" нет Дозвон: гудок "number" — номер телефона
"OutCallConnection" нет Дозвон: соединение "number" — номер телефона
"OutCallEnd" нет Дозвон: завершение "number" — номер телефона
"OutSMS" нет Исходящее SMS "number" — номер телефона, "text" — текст
"InCall" нет Входящий вызов "number" — номер телефона
"InCallConnection" нет Входящий вызов: соединение "number" — номер телефона
"InCallEnd" нет Входящий вызов: завершение "number" — номер телефона
"InSMS" нет Входящее SMS "number" — номер телефона, "text" — текст
"ThermometerUpdate" нет Найден термодатчик "slot" — номер слота (с нуля), "type" — тип ("wired" — проводной, "radio" — радио), "serial" — серийный номер
"TemperatureHigh" да Температура выше порога "message" — текстовое сообщение (название датчика)
"TemperatureLow" да Температура ниже порога "message" — текстовое сообщение (название датчика)
"ThermometerMalfunction" да Термодатчик недоступен "message" — текстовое сообщение (название датчика)
"BatteryLow" да Разряд аккумулятора "voltage" — напряжение в вольтах
"RadioFOBAdded" нет Добавлен брелок или радиореле "slot" — номер слота
"BoilerFail" да Авария котла null
"BoilerFailCancel" да Авария котла устранена null
"Landmark" нет Метка (ZONT Трекер) "label" — имя метки
"ZoneAlarm" да Срабатывание охранной зоны "message" — сообщение, "zone" — номер зоны
"ZoneAlarmCancel" нет Восстановление охранной зоны "message" — сообщение, "zone" — номер зоны
"OTFail" да Авария котла или её устранение (OpenTherm). Аварии нет если поле "c" равно нулю, а массив "f" пуст "c" — код ошибки OEM
"f" — массив флагов сбоя:
  • "sr" — необходимо обслуживание
  • "lr" — требуется ручной сброс
  • "wp" — низкое давление воды
  • "gf" — сбой газа/горелки
  • "ap" — сбой давления воздуха
  • "wot" — перегрев воды
"OTLost" да Потеря связи по OpenTherm null
"OTFound" да Восстановление связи по OpenTherm null
"UploadSuccess" нет Файлы успешно загружены
"UploadFailed" да Не удалось загрузить файлы
"UserEvent" нет Пользовательское событие "message" — сообщение
"UserAlarm" да Пользовательское тревожное событие "message" — сообщение
"ExtSensorWarning" да Предупредительная зона доп. датчика
"ExtSensorAlarm" да Тревожная зона доп. датчика
"CurrentECUErrors" да Текущие ошибки ЭБУ (диагностика двигателя автомобиля) "errors" — коды ошибок OBD-II (массив чисел)
"SavedECUErrors" да Сохранённые ошибки ЭБУ (диагностика двигателя автомобиля) "errors" — коды ошибок OBD-II (массив чисел)

Типы сохраняемых данных

В этом разделе перечислены различные типы данных, которые устройства передают на сервер ZONT, и которые вы можете загрузить с сервера с помощью метода load_data.

Для каждого вида данных указано его строковое название, которое нужно передавать в параметре "data_types" запроса, и которое используется в качестве ключа в возвращаемом ответе. Также описан формат, в котором эти данные возвращаются.

Формат Delta-time Array

Пример кодирования температурных показаний:

[
  [1495098587, 21.4],  // 18.05.2017 12:09:47 — 21.4 °C
  [-60, 21.5],         // 18.05.2017 12:10:47 — 21.5 °C
  [-60, 21.7],         // 18.05.2017 12:11:47 — 21.7 °C
  [-60, 21.4]          // 18.05.2017 12:12:47 — 21.4 °C
]

При передаче сохранённых данных как правило нужно закодировать набор значений, каждое из которых привязано к моменту времени. Например это могут быть GPS-координаты, значения температуры, события. Если при передаче таких данных в формате JSON каждую метку времени передавать в виде полного значения времени, то эти временные метки будут занимать значительный объём данных, иногда превышающий объём самих значений. Для экономии трафика мы используем простой способ дельта-кодирования временных меток, который в дальнейшем называем Delta-time Array.

Delta-time Array — это массив массивов следующей структуры:

[ [time1, ...], [time2, ...], ... [timeN, ...] ]

Первым элементом каждого массива является метка времени. Остальные элементы зависят от характера кодируемых данных.

Метки времени являются целыми числами подчинаются следующему правилу:

Первая метка времени в массиве — всегда положительная. Последующие могут быть как положительными, так и отрицательными.

temperature — показания температурных датчиков

Пример ответа на load_data:

{
  "responses": [
    {
      "ok": true,
      "device_id": 1580,

      "temperature": {
        "41da3643-47b6-4f97-afc9-d9faf9a569de": {
          "name": "Датчик",
          "color": "#c4443b",
          "sort": 1,
          "temperature": [
            [1495011630, 20.2],
            [-60, 20.1],
            [-60, 20.2],
            [-60, 20.2],
            ...
          ]
        }
      }
    }
  ]
}

Этот вид сохраняемых данных используется для устройств ZONT H, Mega SX и H-1000. В него попадают показания проводных и беспроводных температурных датчиков, подключенных к устройству. Их показания сохраняются раз в минуту.

При запросе данных методом load_data температурные показания возвращаются в виде объекта. Полям этого объекта соответствуют уникальные строковые идентификаторы термодатчиков, а значения — объекты со следующей структурой:

Поле Тип Описание
name string Название датчика
color string Цвет датчика, задаваемый пользователем в веб-интерфейсе, в виде hex-строки (#rrggbb)
sort int Задаёт порядок отображения датчиков. При показе пользователю списка датчиков, их следует отсортировать по возрастанию этого поля.
temperature array Массив показаний датчика за запрошенный период в формате Delta-time Array

thermostat_work — данные о работе термостата

{
  "responses": [
    "ok": true,
    "device_id": 1580,

    "thermostat_work": {
      "thermostat_mode": [[1495011630, 1], [-3600, 2], ...],
      "boiler_work_time": [[1495011630, 60], [-60, 60], [-60, 23], [-60, 0], ...],
      "target_temp": [[1495011630, 23], [-3600, 18], ...],
      "power": [[1495011630, true], [-86400, true]],
      "fail": [[1495011630, false], [-86400, false]],
      "zones": {
        "1": {
          "target_temp": [[1495011630, 23], [-3600, 18], ...],
          "worktime": [[1495011630, 60], [-60, 60], [-60, 23], [-60, 0], ...],
        }
      },
      "ot": {
        "s": [[1495011630, ["ch", "fl"]], [-120, ["ch"]], ...],
        "cs": [[1495011630, 57], [-60, 58], ...],
        "ff": [[1495011630, {"c": 0, "f": []}], [-86400, {"c": 0, "f": []}]],
        ...
      }
    }
  ]
}

Устройства ZONT H ежеминутно сохраняют информацию о работе термостата и значения различных параметров.

При запросе этого типа данных с помощью метода load_data будет возвращён объект со следующими полями:

Поле Тип Описание
thermostat_mode DTA<int>

Режим термостата. Кодируется числом.

Для H-1/H-2 с прошивками ниже xx:82 и H-1000/Mega SX с прошивками ниже xx:172 число означает:

  • 0 — антизаморозка/выключен
  • 1 — комфорт
  • 2 — эконом
  • 3 — расписание

Для более новых прошивок число означает номер задаваемого пользователем режима. Если вам необходима описание как получить настройки режимов — напишите нам.
boiler_work_time DTA<int>

(для однозонного термостата) Количество секунд, в течение которых котёл работал за последнюю минуту.

Под работой котла здесь понимается состояние выхода термостата. То есть при отсутствии основного питания, значение этого параметра не будет соответствовать действительности, так как реле не будет на самом деле переключаться.
target_temp DTA<float> Целевая температура (для однозонного термостата)
pza_t DTA<float> Расчётная температура ПЗА
dhw_t DTA<float> Заданная температура ГВС
power DTA<bool>

Наличие основного питания: true — питание есть, false — питания нет.

Термостаты ZONT H при отсутствии питания не управляют термостатом, реле переходит в нормальное состояние (см. документацию).
fail DTA<bool> Признак аварии котла: true — авария есть, false — аварии нет. При наличии OpenTherm больше информации об аварии можно получить в поле ot.
gate DTA<bool> Активность режима Комнатного термостата: true — режим включен, термостат управляется внешним комнатным термостатом; false — режим выключен, термостат управляет по обычному алгоритму.
ot object Состояние OpenTherm. Поля объекта соответствуют аналогичным полям состояния last-boiler-state.ot, а значениями полея являются массивы Delta-time array из соответствующих величин.
zones object

(для многозонного термостата) Информация о работе отдельных зон. Полями объекта являются номера зон, а значениями — объекты со следующими полями:

  • target_temp (DTA<float>) — целевая температура зоны
  • worktime (DTA<int>) — время активности зоны в секундах за последнюю минуту

custom_controls — история состояний пользовательских статусов

Пример ответа на custom_controls

{
  "responses": [
    {
      "ok": true,
      "device_id": 18945,

      "custom_controls": [
        [1498710530,0],
        [-8,2],
        [-6277,3],
        [-15,1],
        [-4961,0],
        ...
      ]
    }
  ]
}

Сохраняемые данные типа custom_controls используются для устройств Mega SX, H-1000 и ZTC. Запросив этот тип данных можно получить историю переключений пользовательских статусов.

При запросе данных с помощью метода load_data данные возвращаются в виде массива в формате Delta-time Array. В качестве значений в этом массиве передаются целые числа. Каждый бит в двоичном представлении числа обозначает состояние статуса с соответствующим идентификатором.

Например, от сервера получен такой ответ:

[[1498710120, 0], [-86, 6], [-5, 2]]

Этот ответ обозначает:

Типы устройств

В рамках системы ZONT выпускается множество устройств с различным назначением. Каждой модели соответствует свой идентификатор.

Идентификатор Модель Описание
T100 ZONT H-1/H-1V Домашний GSM-термостат
T102 ZONT H-2 Домашний Wi-Fi-термостат
L1000 ZONT L-1000 Многофункциональный программируемый GSM/Wi-Fi-термостат
ZTC-100 ZTC-100 Спутниковый поисковый модуль
ZTC-110 ZTC-110 Спутниковый охранно-поисковый модуль
ZTC-500 ZTC-500 Автомобильная сигнализация
ZTC-700 ZTC-700 Автомобильная сигнализация
ZTC-700M ZTC-700M Автомобильная сигнализация
ZTC-701M ZTC-701M Автомобильная сигнализация
ZTC-710 ZTC-710 Автомобильная сигнализация
ZTC-720 ZTC-720 Автомобильная сигнализация
tracker ZONT Трекер Приложение для Android
ZTA-110 ZTA-110 Объектовая сигнализация
SX250 Mega SX-LRW Объектовая сигнализация
SX170 Mega SX-170 Объектовая сигнализация
SX300 Mega SX-300 Объектовая сигнализация
SX350 Mega SX-350 Объектовая сигнализация

Параметры устройств

У каждого устройства есть Настройки и Состояния.

Настройками называют те параметры, значения которых обычно редко изменяются и которыми есть смысл управлять при отсутствии связи с устройством (например: список доверенных номеров, целевые температуры). Состояния — это параметры, описывающие устройство только в данный момент, значения которых могут меняться в зависимости от внешних воздействий (например: состояние охраны, уровень сигнала).

Получить текущие Настройки устройств можно с помощью метода devices. Если при запросе указать "load_io": true, то в каждом объекте, описывающем устройство, в поле "io" также будут возвращены Состояния устройств.

Изменить Настройки можно с помощью метода update_device. Управлять Состояниями — с помощью метода set_io_port.

Ниже приведены описания всех параметров устройств, сгруппированные по области применения. Обратите внимание, что одно и то же устройство может относиться к нескольким разделам.

Общие для всех типов устройств

Настройки

{
  "id": 1209,
  "serial": "973BF3309550",
  "name": "Сигнализация"

  ...
}
Название Тип Описание
id int Идентификатор устройства
serial string Серийный номер
name string Название

Состояние беспроводной сети

Настройки

{
  "balance": {
    "ussd": "*102#",
    "warning": true,
    "limit": 30
  },
  "trusted_phones": "+79082394312,+79102417612",
  "gsm_roaming": "same"

  ...
}
Название Тип Описание
balance object

Настройки отслеживания баланса SIM-карты

Поле Тип Описание
ussd string USSD-команда для запроса
warning bool Предупреждать ли при снижении ниже порога
limit int|null Порог, ниже которого происходит оповещение
trusted_phones string Доверенные номера телефонов, разделённые запятой
gsm_roaming string

Разрешение использования интернета в роуминге

  • "no" — запрет роуминга
  • "same" — разрешено во внутресетевом роуминге
  • "any" — разрешено в любом роуминге

Состояния

{
  "io": {
    "balance-value": "56",
    "gsm-state": {
      "level": 29,
      "operator": "MTS",
      "state": "home-network"
    },
    ...
  }

  ...
}
Название Тип Описание
balance-value string|null Текущее значение баланса SIM-карты
gsm-state object

Состояние GSM/Wi-Fi

Поле Тип Описание
level int Уровень сигнала [0..31]
operator string Название сети (имя оператора)
state string
  • not-registered — не зарегистрирован
  • home-network — в домашней сети
  • searching — поиск сети
  • rejected — сеть отказала в регистрации
  • roaming — в роуминге

Охрана (ZTC, Mega SX, ZONT H)

Состояния

{
  "io": {
    "guard-state": "enabled",
    "siren": false
    ...
  }

  ...
}
Название Тип Описание
guard-state string "enabled" если охрана активна, "disabled" если не активна или "enabling" если выполняется постановка на охрану
siren bool сирена активна в данный момент

Взаимодействие с автомобилем (ZTC)

Настройки

{
  "temperature_conf": {
    "assignments": [
      "cabin",
      "engine"
    ]
  }
  ...
}
Название Тип Описание
temperature_conf object Настройка термодатчиков. Объект со следующими полями:
Название Тип Описание
assignments array

Массив строк, описывающих назначение термодатчиков. Каждый элемент определяет назначение соответствующего по номеру датчика из состояния "temperature".

Возможные назначения:

  • "engine" — температура двигателя
  • "cabin" — температура салона
  • "outside" — температура снаружи
  • "none" — назначение не задано

Состояния

{
  "io": {
    "engine-block": false,
    "webasto": false,
    "auto-ignition": {
      "available": true,
      "state": "enabled",
      "configuration": {
        "engine": true,
        "webasto": false
      },
      "current_mode": {
        "engine": true,
        "webasto": false
      },
      "until": 1478811896
    },
    "ignition-state": true,
    "engine-state": true,
    "doors": false,
    "door-1": null,
    "door-2": null,
    "door-3": null,
    "door-4": null,
    "hood-trunk": null,
    "hood": false,
    "trunk": false,
    "ecu-diagnostics-enabled": true,
    "temperature": [
      {"state": "ok", "value": 21},
      {"state": "ok", "value": 73},
      {"state": "disconnected", "value": 0}
    ]
    ...
  }

  ...
}
Название Тип Описание
engine-block bool активна ли блокировка двигателя
webasto bool включен ли предпусковой подогреватель (ZTC-1xx)
auto-ignition object

состояние автозапуска (ZTC-7xx, ZTC-5xx)

Поле Тип Описание
available bool Доступность автозапуска
state string

Состояние автозапуска

  • "disabled" — автозапуск выключен
  • "enabling" — запуск двигателя
  • "enabled" — двигатель заведён
  • "webasto" — включен предпусковой подогреватель
  • "webasto-confirmed" — включен предпусковой подогреватель и это подтверждено сигналом от подогревателя
configuration object Два булевых поля `"engine"` и `"webasto"` означают, настроен ли запуск соответственно двигателя и подогревателя
current_mode object Два булевых поля `"engine"` и `"webasto"` означают, используется ли запуск соответственно двигателя и подогревателя в текущей сессии автозапуска
until int|null Планируемое время отключения автозапуска
ignition-state bool Включено ли зажигание
engine-state bool Запущен ли двигатель
doors bool Открыта ли хотя бы одна дверь (при подключении дверей общим сигналом)
door-1, door-2, door-3, door-4 bool Открыта ли каждая из четырёх дверей
hood-trunk bool Открыт ли капот или багажник (при подключении их общим сигналом)
hood, trunk bool Открыты ли соответственно капот и багажник
ecu-diagnostics-active bool Активна ли диагностика двигателя
temperature array Показния термодатчиков. Массив, состоящий из объектов с полями:
Поле Тип Описание
state string Состояние датчика: "ok" — датчик исправен, "malfunction" — неисправен, "disconnected" — не подключен
value int Температура в градусах Цельсия (если state равен "ok")

Управление отоплением (ZONT H)

Старый и новый формат режимов отопления

Ранние весии прошивок ZONT H-1, H-1V, H-2 поддерживали ровно 4 режима отопления: «Эконом», «Комфорт», «Расписание» и «Антизаморозка/Выключен». В новых версиях появились более гибкие настраиваемые режимы, а также появилась отдельная концепция «целевых температур», которые имеют приоритет над текущим режимом отопления, в случае если целевая температура отредактирована пользователем вручную.

Это изменение отразилось и на API. В описании настроек ниже те поля, которые относятся только к старому или только к новому формату режимов, будут отмечены комментарием.

В устройстве всегда работает либо старая, либо новая схема режимов, они не совмещаются. Тем не менее для новой схемы API всё равно выдаёт для устройства и старые поля тоже для ограниченной обратной совместимости. Поля, соответствующие новому формату, имеют приоритет.

Версии прошивок, поддерживающих новый формат:

Модель Версия прошивки
ZONT H-1, H-1V, H-1B, H-2 ≥ xx:82
ZONT H-1000, H-2000 любая

Настройки

{
  // старый формат режимов
  "thermostat_mode": "comfort",  
  "thermostat_mode_temps": {
    "econom": 15,
    "comfort": 21.5,
    "idle": 5,
    "full_off": false
  },

  // новый формат режимов
  "thermostat_ext_mode": 1,
  "thermostat_ext_modes_config": {
    "0": {
      "active": true,
      "name": "Эконом",
      "zone_sensors": {"0": null, "1": null},
      "zone_temp": {"0": 15, "1": 15} 
    },
    "1": {
      "active": true,
      "name": "Расписание",
      "schedule_number": 1,
      "zone_sensors": {},
      "zone_temp": {},
    },
    "2": {
      "active": true,
      "name": "Выключен",
      "zone_temp": {"0": false, "1": false},
    },
    "3": {"active": false, ...},
    ...
  },

  "tempschedule": {
    "day": [23, 23, 23, ..., 23],
    "week": {
      "0": [16, 16, 16, ..., 16],
      ...
      "6": [21.5, 21.5, ..., 21.5]
    }
  },

  "thermometers": [
    {
      "uuid": "57d5c19005b605000bc4502b",
      "is_assigned_to_slot": true,
      "name": "Кухня",
      "color": "#a05be5",
      "functions": [{"f": "control", "zone": 1}],
      "limits": {
        "high": 30,
        "low": 16
      },
      "type": "wired",
      "last_value_time": 1478383975,
      "last_state": "ok",
      "last_value": 21.2
    }
    ...
  ],

  "ot_enabled": true,
  "ot_mode": "analog",
  "ot_max_setpoint": 80,
  "ot_min_setpoint": 5,
  "ot_max_ml": 100,
  "ot_dhw_setpoint": 46,
  "ot_min_wp": 0,
  "ot_config": ["ch", "dhw"],
  "ot_save_params": ["bt", "dt", "ot"]

  ...
}
Название Тип Описание
thermostat_mode string (Только для старого формата режимов)
Режим термостата. Возможные значения:
  • "econom" — Эконом
  • "comfort" — Комфорт
  • "schedule" — Расписание
  • "idle" — Антизаморозка/выключен
thermostat_mode_temps object (Только для старого формата режимов)
Целевая температура фиксированных режимов термостата. Объект имеет следующие поля:
  • econom (number) — целевая температура режима Эконом
  • comfort (number) — целевая температура режима Комфорт
  • idle (number) — целевая температура режима Антизаморозка
  • full_off (bool) — отключать регулирование в режиме Антизаморозка. Если равно true, то вместо режима Антизаморозка используется режим Выключен
thermostat_ext_mode int (Только для нового формата режимов)
Номер текущего режима отопления. Соответствует индексу в объекте thermostat_ext_modes_config.
thermostat_ext_modes_config object (Только для нового формата режимов)
Конфигурация режимо отопления. Объект (не массив!), ключами которого являются номера режимов (начиная с нуля), а значениями — объекты конфигурации режима. Эти объекты имеют следующие поля:
  • active (bool) — Настроен ли этот режим (существует ли он)
  • hidden (bool) — Скрыт ли режим (отображается ли его кнопка на странице управления устройством)
  • name (string) — Название режима
  • schedule_number (int|null) — Заданное для режима расписание.
    null — расписание не используется.
    1 — используется недельное расписание.
    2...8 — на каждый день используется расписание понедельника...воскресенья.
  • zone_temp (object) — Фиксированные целевые температуры отопительных зон, заданные для этого режима. Объект, ключами которого являются номера отопительных зон (нулевая зона — ГВС), а значения могут быть:
    • null — целевая температура для этой зоны не задана (например, если режим использует расписание)
    • false — зона отключена в этом режиме.
    • число — целевая температура этой зоны, °C
  • zone_sensors (object) — Переназначение целевых датчиков для отопительных зон. Объект, ключами которого являются номера отопительных зон (нулевая зона — ГВС), а значениями -- номера слотов целевых датчиков (соответствующие полю thermometers[...].slot), либо null если используется датчик по умолчанию.
tempstep float Шаг изменения температуры кнопками – и + в веб-интерфейсе и мобильном приложении.
tempschedule object Расписание температур. Применяется устройством когда выставлен режим «Расписание».
  • week (object) — недельное расписание. Имеет поля "0", "1", ..., "6", соответствующие дням недели (0 — понедельник, 6 — воскресенье). Значениями являются массивы из 24 элементов с температурами для каждого.
  • day (array) — дневное расписание. В данный момент не используется устройствами.
thermometers array Данные о термодатчиках. Массив объектов, каждый из которых имеет следующие поля:
  • uuid (string) — уникальный строковый идентификатор датчика.
  • is_assigned_to_slot (bool) — если true, то этот термодатчик в данный момент зарегистрирован в термостате. Термодатчики с этим полем, равным false следует игнорировать при анализе. Они могут быть в массиве в том случае, если датчик был отключен от термостата, а затем был произведёт сброс датчиков.
  • slot (int|null) — номер датчика если он в данный момент зарегистрирован в термостате, либо null если не зарегистрирован
  • serial (string) — серийный номер
  • name (string) — название
  • color (string) — цвет в веб-интерфейсе в html-нотации
  • functions (array) — назначения датчика. Массив объектов со следующими полями:
    • "f" (string) — функция. Возможные значения:
      • "control" — регулирование
      • "control-reserve" — резервное регулирование
      • "heat" — температура теплоносителя
      • "outside" — температура снаружи
    • "zone" (int) — номер отопительной зоны. Указывается для функций регулирования и t° теплоносителя. Основная отопительная зона имеет номер 1, дополнительные — 2 и выше.
  • limits (object) — пороги допустимых значений. Величины порогов указаны в дочерних полях low и high. Если порог не задан, то соответствующее поле равно null.
  • last_value_time (int) — время получения последней информации о показании датчика (полей `last_state` и `last_value`). Время в секундах с 1970-01-01 00:00:00 (UTC)
  • last_state (string) — состояние датчика. Возможные значения:
    • "ok" — датчик исправен
    • "malfunction" — датчик неисправен
  • last_value (number) — показание датчика, °C
ot_enabled bool OpenTherm включен
ot_mode string Режим работы OpenTherm: "analog" — обычный, "relay" — псевдорелейный
ot_max_setpoint float Максимальная заданная температура теплоносителя (OpenTherm)
ot_min_setpoint float Минимальная заданная температура теплоносителя (OpenTherm)
ot_max_ml float Максимальный уровень модуляции горелки в процентах (OpenTherm)
ot_dhw_setpoint float Заданная температура ГВС (OpenTherm)
ot_min_wp float Минимальное давление теплоносителя (OpenTherm)
ot_config array

Настройки функционала OpenTherm. Массив, содержащий строковые флаги:

  • "ch" — включение отопления
  • "dhw" — включение ГВС
  • "cl" — включение охлаждения
  • "ch2" — включение второго контура отопления
ot_save_params array

Параметры OpenTherm для ежеминутного сохранения. По выбранным параметрам можно будет увидеть графики в веб-интерфейсе и приложениях ZONT. Массив, содержащий строковые флаги:

  • "bt" — фактическая температура теплоносителя
  • "dt" — фактическая температура ГВС
  • "rwt" — температура обратного потока
  • "ot" — уличная температура
  • "rml" — уровень модуляции горелки
  • "wp" — давление теплоносителя
  • "fr" — скорость потока ГВС

Параметры "s" (статус), "cs" (расчётная температура теплоносителя отопления) и "ff" (коды ошибок) сохраняются всегда, независимо от этого параметра.

Состояния

{
  "io": {
    "last-boiler-state": {
      "time": 1479881662,
      "boiler_work_time": 60,
      "thermostat_mode": "comfort",
      "target_temp": 22.0,
      "gate": false,
      "power": true,
      "fail": false,
      "pza_t": null,
      "ot": {
        "s": ["ch", "fl"],
        "cs": 37,
        "ff": {"f": [], "c": 0},
        "bt": 35,
        "dt": 32,
        "ot": -12.0
      }
    }
    ...
  }

  ...
}
Название Тип Описание
last-boiler-state object

Текущий статус термостата. Термостат присылает обновлённый статус раз в минуту. Имеет следующие поля:

  • time (int) — время получения статуса (в секундах с 1970-01-01 00:00:00 UTC)
  • boiler_work_time (int) — время работы котла в секундах за последнюю минуту. Неравенство нулю этого поля можно использовать как признак работы котла.
  • thermostat_mode (string) — режим термостата ("econom", "comfort", "schedule", "idle")
  • gate (bool) — включён ли режим шлюза для внешнего комнатного термостата
  • target_temp (float) — целевая температура
  • power (bool) — наличие внешнего питания
  • fail (bool) — присутствует ли авария котла
  • pza_t (float) — расчётная температура ПЗА
  • ot (object) — состояние OpenTherm
    • s (array) — массив флагов состояния
      • "f" — авария
      • "ch" — отопление включено
      • "dhw" — ГВС включено
      • "fl" — горелка работает
      • "cl" — охлаждение работает
      • "ch2" — второй контур отопления включен
      • "di" — диагностическая индикация
    • cs (float) — расчётная температура теплоносителя отопления
    • ff (object) — состояние аварии
      • c (int) — OEM-код аварии
      • f (array) — флаги аварии
        • "sr" — требуется обслуживание
        • "lr" — требуется ручной сброс
        • "wp" — низкое давление теплоносителя
        • "gf" — сбой газа/горелки
        • "ap" — сбой давления воздуха
        • "wot" — превышение температуры
    • bt (float) — фактическая температура теплоносителя
    • dt (float) — фактическая температура ГВС
    • ot (float) — уличная температура
    • rwt (float) — температура обратного потока
    • rml (float) — относительный уровень модуляции в процентах
    • wp (float) — давление теплоносителя (бар)
    • fr (float) — скорость потока ГВС (литр/мин)

Пользовательские команды и статусы (ZTC-7xx, Mega SX)

{
  "custom_controls": [
    { // таких блоков может быть несколько
      "statuses": [
        {
          "id": 0,
          "type": "status",
          "name": "Насос"
        }
      ],
      "commands": [
        {
          "id": 0,
          "type": "command",
          "name": "Включить насос"
        },
        {
          "id": 1,
          "type": "command",
          "name": "Выключить насос"
        }
      ]
    }
  ],

  "io": {
    "custom_controls_state": {
      "0": 1,
      "1": 1
      ...
    }

    ...
  }

  ...
}

Настройки

Название Тип Описание
custom_controls array

Данные о пользовательских командах и статусах, задаваемых в настроечной утилите. Массив элементов, каждый из которых представляет собой ноль или более кнопок и не более одного статуса, сгруппированные в один графический элемент интерфейса (кнопку или индикатор).

Каждый объект имеет следующие поля:

  • commands — массив команд
  • statuses — массив статусов

Статус — это некоторое состояние устройства, которое может принимать значения 0 или 1 (например, 0 — свет не горит, 1 — свет горит). Команда — запрос устройству на выполнение какого-то действия (например, включить свет)

Каждая команда или статус имеют следующие поля:

  • id (int) — идентификатор
  • name (string) — название

Отправить устройству команду из списка можно с помощью метода send_custom_command.

Состояния

Название Тип Описание
custom_controls_state object Текущие значения пользовательских статусов (см. настройку custom_controls). Имеет форму {"0": 1, "1": 1, ...}. Каждому идентификатору статуса ставится в соответствие 0 или 1 в зависимости от текущего значения этого статуса в устройстве.

Получение архивов данных

С помощью API вы можете запросить выгрузку архива со всеми данными по устройству за нужный период времени.

Чтобы получить архив, нужно сначала запросить его создание методом generate_archive, а затем скачать полученный файл с помощью метода download_generated_archive.

generate_archive — создать архив

curl 'https://my.zont.online/api/generate_archive'    \
  -u 'demo:demo'                                      \
  -H 'X-ZONT-Client: your@email.com'                      \
  -H 'Content-Type: application/json'                 \
  -d '{"device_id": 1209, "split_by": "days",
       "mintime": 1486252800, "maxtime": 1486339200}'

import requests

url = 'https://my.zont.online/api/generate_archive'
data = {
    'device_id': 1209,
    'mintime': 1486252800,
    'maxtime': 1486339200,
    'split_by': 'days'
}

headers = {'X-ZONT-Client': 'your@email.com'}
result = requests.post(url, json=data, auth=('demo', 'demo'), headers=headers).json()

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$url = 'https://my.zont.online/api/generate_archive';
$data = array(
    'device_id' => 1209,
    'mintime' => 1486252800,
    'maxtime' => 1486339200,
    'split_by' => 'days'
);

$headers = array('X-ZONT-Client' => 'your@email.com', 'Content-Type' => 'application/json');
$options = array('auth' => array('demo', 'demo'));
$request = Requests::post($url, $headers, json_encode($data), $options);
$response = json_decode($request->body, true);

Результат:

{
  "ok": true,
  "archive_id": "58f4b58205b605000733f5c6"
}

POST https://my.zont.online/api/generate_archive

Запросить создание файла с архивом данных.

Параметры

Имя Тип Обязательный Описание
device_id int да ID устройства
mintime int да Начало временного диапазона (включительно)
maxtime int да Конец временного диапазона (включительно)
split_by string да Интервал разбиения данных по файлам в архиве. "days" — отдельные файлы на каждый день, "months" — отдельные файлы на каждый месяц.

Время указывается в целых секундах, прошедших с 1970-01-01 00:00:00 (UTC). Не забудьте сделать поправку на нужный часовой пояс!

Результат

Ответ будет содержать поле archive_id, содержащее уникальный строковый идентификатор созданного архива. Этот идентификатор нужно указать в методе download_generated_archive чтобы скачать файл архива.

download_generated_archive — скачать файл архива

curl 'https://my.zont.online/api/download_generated_archive?archive_id=58f4b58205b605000733f5c6' \
  -u 'demo:demo' >archive.zip

import requests

url = 'https://my.zont.online/api/download_generated_archive'
data = {'archive_id': '58f4b58205b605000733f5c6'}
result = requests.get(url, data, auth=('demo', 'demo'))
with open('archive.zip', 'wb') as f:
    f.write(result.content)

<?php
require_once 'Requests.php';
Requests::register_autoloader();

$archive_id = '58f4b58205b605000733f5c6';
$url = 'https://my.zont.online/api/download_generated_archive?archive_id=' . $archive_id;
$options = array('auth' => array('demo', 'demo'));
$response = Requests::get($url, array(), $options);
file_put_contents('archive.zip', $response->body);

Результат будет записан в файл archive.zip

GET https://my.zont.online/api/download_generated_archive

Скачать файл, созданный методом generate_archive. Обратите внимание, этот метод работает по запросу GET.

Параметры

Имя Обязательный Описание
archive_id да идентификатор архива

Результат

В ответ сервер отправит zip-архив с данными.

curl python php