Перейти к содержимому

k12cloud.ru — это сервис-посредник между вашими IoT устройствами и сторонними сайтами и сервисами. На данный момент он имеет для независимых друг от друга API (программных интерфейса), которые вы можете использовать:

  • Отправка уведомлений с ваших IoT устройств на электронную почту, в telegram (от имени бота) или в vk (от имени сообщества). Отправив всего один запрос к API вы можете отправить сообщения по одному или нескольким каналам, чтобы как можно быстрее прочитать их.
  • Получение произвольных данных с ваших IoT устройств, их хранение в течение какого-то периода времени (на текущий момент максимум год), а также их «централизованную» пересылку на сторонние ресурсы, например: народный мониторинг, thing speak, open-monitoring.online и другие. На данный момент полученные данные можно просматривать только в виде таблицы, данные никак не обрабатываются и не изменяются.

Основной назначение сервиса — вынести не совсем свойственные автоматическим IoT устройствам функции «за пределы» hardware, что позволит облегчить написание кода прошивок, хранить в прошивке меньше корневых сертификатов, и легко перенастраивать уведомления без вмешательства в прошивку. Перечисленные API не зависят друг от друга, поэтому вы можете использовать только тот функционал, который вам нужен. Ниже вы найдете очень краткую инструкцию по использованию данных API.

На данный момент сервис предоставляется полностью бесплатно, и взимание какой-либо обязательной платы не планируется. Сервис предоставляется «как есть», без каких-либо гарантий со стороны автора.

Если вы пожелаете предложить новую идеи или поддержать развитие проекта донатом — вы можете связаться со мной в telegram: @kotyara1971 или по почте: kotyara12@yandex.ru.

IoT Device Manager

Прежде чем вы сможете воспользоваться любым из предлагаемых API, вам необходимо зарегистрироваться и зайти в панель IoT Device Manager.

Слева находится список ваших устройств. Если вы зашлю сюда в первый раз, он будет пуст — нажмите кнопку «Добавить» и создайте первое устройство. Иначе выделите устройство в списке, с которым вы хотите работать.

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

 

API отправки уведомлений

Как и следует из названия, данное API целиком и полностью предназначено для отправки уведомлений. Но прежде чем вы сможете это сделать, необходимо открыть вкладку «Уведомления» и настроить каналы уведомлений, по которым вы хотите их получать. Это могут быть: telegram bot api, vk bot api или самая обычная электронная почта.

Важно! Для telegram и vk нужно обязательно указать так называемый токен бота, как его получить описано здесь. Для электронной почты достаточно адреса получателя.

Вы можете проверить работоспособность сервиса, отправив тестовое сообщение с помощью кнопки в верхнем правом углу сервиса. Если все в порядке — можно попробовать отправить сообщение уже из вашего устройства. Как это сделать технически — вы можете прочитать здесь: для arduino либо для esp-idf.

API уведомлений на текущий момент имеет всего одну функцию send-notification:

https://k12cloud.ru/api/send-notification

Функция имеет три параметра:

  • token (обязательный) — write_token устройства
  • type (опциональный) — тип сообщения: main, alarms, service, settings, other (по умолчанию используется main)
  • message (обязательный) — собственно текст сообщения с HTML-разметкой (если это необходимо)

Для обращения к сервису вы можете можете использовать HTTP-методы GET или POST:

// GET-запрос
GET: https://k12cloud.ru/api/send-notification?token=c25b54262fafd16cd49c93988ef326c5&type=alarms&message=Текст%20сообщения

// POST-запрос с текстовыми заголовками
POST (form-data): token=c25b54262fafd16cd49c93988ef326c5&type=alarms&message=Текст сообщения

// POST-запрос с JSON-пакетом
POST (JSON): {"token":"c25b54262fafd16cd49c93988ef326c5","type":"alarms","message":"Текст сообщения"}

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

Проверить корректность отправки уведомлений можно на вкладке «Журнал». Журнал храниться в течение 30 суток.

API получения и перенаправления данных

Данное API позволяет хранить некие данные, полученные с ваших устройств, и самое главное — перенаправлять их на другие сервисы: народный мониторинг, thing speak, open-monitoring.online и другие (которые поддерживают отправку данных GET — запросом). То есть отправляя один единственный пакет данных на k12cloud.ru, вы автоматически рассылаете их сразу везде — куда вам нужно. Это позволяет экономить время отправки (примечание: только при асинхронных запросах на ESP) и ресурсы прошивки. Таким образом пока что единственный смысл всего этого — если вы хотите отправлять ваши данные с устройств сразу на несколько сервисов (так как они обладают разными возможностями).

Для этого необходимо выполнить следующие подготовительные шаги:

1. Настройте список полей данных, которые вы будете  получать с устройства. Сделать это можно на вкладке «Поля данных«. Например это может выглядеть так:

Полученные данные в заданном вами формате можно просмотреть (после получения первого пакета) на вкладке «Данные». В дальнейшем, возможно, будут добавлены фильтры и какой-то dashboard )(но не обязательно, так как это не основная цель проекта).

2. Теперь вы можете отправить данные с помощью функции API add-data: 

https://k12cloud.ru/api/add-data

Методы вызова:

GET: https://k12cloud.ru/api/add-data?token=c25b54262fafd16cd49c93988ef326c5&temp=25.5&humd=65&press=1013

POST (JSON): {"token":"c25b54262fafd16cd49c93988ef326c5","temp":25.5,"humd":65,"press":1013}

POST (form-data): token=c25b54262fafd16cd49c93988ef326c5&temp=25.5&humd=65&press=1013

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

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

3. Настройте список пересылаемых данных. Откройте вкладку «Пересылка» — где вы можете настроить пересылку данных на другие сервисы (транзит данных). Транзит данных задается в виде шаблона URL GET-запроса, где вместо данных необходимо указать либо номера полей {f1} либо их названия {temperature}:

Примечание: транзит выполняется только в моменты получения данных, но с учетом заданного интервала. Например вы можете отправлять данные на сервис каждые 60 секунд, а в настройках транзита указали интервал 300 секунд. В этом случае транзит будет выполнен только на каждой пятой отправке данных на сервис. Это позволяет выполнять требования сторонних сайтов, на которые вы хотите отправлять данные. Если вы не отправляете данные на k12cloud.ru длительное время, то и на сторонние сервисы ничего не попадет.

Проверить корректность получения и транзита данных можно на вкладке «Журнал». Журнал храниться в течение 30 суток.

В дальнейшем планируется добавить API для чтения хранящихся данных, но это пока только в планах

API получения диагностических данных

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

Набор полей здесь может быть следующий (не все поля обязательно отправлять):

  • device_timestamp — время на устройстве в UNIXTIME (int64)
  • error_count — общий счетчик сбоев и ошибок на устройстве с момента последнего сброса
  • sensor_error_count — счетчик сбоев сенсоров и периферийного оборудования
  • ram_dram — общий размер памяти для обычной RAM
  • ram_free — свободный размер памяти для обычной RAM
  • psram_dram — общий размер памяти для PSRAM, если установлена
  • psram_free — cвободный размер памяти для PSRAM, если установлена
  • nvs_total — общий размер NVS раздела в записях
  • nvs_free — свободный размер NVS раздела
  • cpu_usage — загрузка процессора
  • rssi — уровень сигнала WiFi

Дополнительные диагностические данные, хранящиеся в JSON-формате:

  • ping_data — данные проверки доступности узлов, например [{"host":"8.8.8.8","time":15,"loss":0}, ...]
  • tasks_data — cписок задач в JSON формате
  • extra_data — дополнительные сведения при необходимости

Основные диагностические данные можно просматривать в виде таблицы на вкладке «Диагностика«. Раздел находится еще в разработке.