Загальні відомості та обмеження передачі показань датчиків
Передавати показання датчиків можна за допомогою протоколів TCP/UDP (в більшості випадків) або HTTP(S) GET/POST (для початківців або з шифруванням), а також MQTT (для приладів зі зворотним зв'язком) і JSON для одночасної передачі даних відразу декількох приладів і інтеграції з іншими системами моніторингу.
Максимальний розмір пакета даних 4 КБ для TCP/POST, 2 КБ для GET, 512 байт для UDP (обмеження MTU).
Якщо з моменту TCP підключення пройшло 10 секунд (крім MQTT), то такі підключення закриваються примусово, тому рекомендуємо спершу опитати всі датчики на вашому приладі, записати їх показання в буфер, а тільки потім встановлювати підключення і передати пакет даних на сервері.
Дані обробляються і завантажуються в базу пакетно 1 раз в хвилину (команди MQTT негайно), відповідно і показання датчиків також оновлюються щохвилини. При відправці показань частіше ніж 1 раз в хвилину прилад потрапляє в бан до усунення проблеми його власником.
Допустимий інтервал запису показань датчиків в історію (для побудови графіків, вивантаження в зовнішні системи і CSV) становить 5 хвилин і може бути зменшений для партнерів і донаторів.
Забороняється розголошувати свої унікальні MAC-адреси приладів і датчиків на сторонніх ресурсах і при публікації вихідних кодів для передачі показань на narodmon.ru слід їх маскувати щоб уникнути проблем сліпого копіювання чужого коду серед новачків і, як наслідок, конфліктів унікальності MAC в проекті.
За наявності помилок у протоколі приладу його IP блокується на 15 хвилин. Захід вимушений бо боти-сканери вразливостей втомили і їх активність зростає.
Як налагодити (перевірити на помилки та активність) дані з приладу
В процесі розробки нових приладів нерідко виникає необхідність налагодити його протокол передачі показань з метою виявлення і виправлення помилок в ньому, але як бути, якщо ліміт приладів в проекті не дозволяє вам це зробити ?
1. Якщо ваш прилад знаходиться у вашій домашній/офісній мережі і стало бути має той же публічний IP адреса, що і ваш браузер, то для налагодження ви можете скористатися розділом сайту Профіль \ дані з мого IP (після авторизації) або ж по короткому посиланню narodmon.ru/me
2. Якщо ж ви налагоджуєте прилад, підключений до мобільного Інтернету (тобто його публічний IP не збігається з вашим браузером), то ви можете скористатися посиланням виду: narodmon.ru/dev/DEVICEMAC
* DEVICEMAC замінити на MAC вашого приладу (без: і -) в будь-якому регістрі. Якщо прилад вже зареєстрований в проекті, то читаємо далі п.3.
3. Для успішно зареєстрованих приладів налагоджувальна інформація знаходиться в розділі сайту Датчики \ Налаштування \ дані, отримані від приладу.
PS в отладочной інформації доступні дані про всі пакетах даних отриманих сервером за останні пару годин від вашого приладу, а також помилки в його протоколі (якщо такі є). Якщо ж цих даних немає, значить Або IP / MAC приладу відрізняється від зазначеного вами або у приладу немає доступу в Інтернет (невірно налаштований або не оплачений).
Перелік типових помилок у відповіді сервера:
* INTERVAL...<5m - прилад передає дані частіше, ніж йому дозволено (за замовчуванням 5 хвилин).
* Sensor...invalid value... - датчик передав на сервер неприпустиме показання (наприклад букви замість цифр).
* Sensor...out of range... - датчик передав показання за межами допустимого діапазону для його типу даних.
* ... is too big-датчик передав занадто велике показання.
* UnixTime > NOW-зазначений час в UnixTime (UTC+0) показання більше поточного.
* MAC_MISSED - пропущена метрика датчика або MAC (серійний номер) приладу.
* Device MAC...is invalid - неприпустимий MAC (серійний номер) приладу.
* # # _MISSED_AT_THE_END - відсутня ознака кінця пакету даних # #(пакет обрізався при відправці).
* BANNED - прилад заблокований власником або адміністратором.
* IP binding enabled. Data from...is ignored - у приладу включена прив'язка до IP, але дані надходять з іншого IP і тому ігноруються (можливо провайдер змінив Ваш IP або виявлено конфлікт унікальності MAC приладів).
Дані, необхідні для передачі на сервер проекту
Поле MAC (ID) - унікальний ідентифікатор приладу в проекті
Найчастіше складається з 12-18 символів A-Z і 0-9 іноді розділених '-' або ':'.
Призначений для ідентифікації приладу (і постачальника по префіксу) в проекті і його прив'язки до власника і до карти в розділі Датчики.
Розробникам приладів рекомендується використовувати персональний префікс для своїх приладів для забезпечення унікальності в проекті і встановлення авторства, а також уникати часто повторюваних знаків як в прикладі нижче.
TCP/UDP:
#00:00:00:00:00:00
...
##
GET/POST:
id=00:00:00:00:00:00&...
Поле NAME - назва приладу в проекті
Необов'язкова до передачі назва пристрою моніторингу в кодуванні UTF-8 або Windows-1251 за фактом перейменування. Передається в TCP/UDP в першому рядку після MAC адреси пристрою і роздільника #, а в GET/POST передається окремим параметром NAME. Рекомендується для пристроїв з веб-інтерфейсом або з утилітою конфігурації, в яких можна вказати аліаси (назви).
TCP/UDP:
#MAC#Назва
...
##
GET/POST:
ID=MAC&NAME=Назва&...
Поле OWNER - власник приладу в проекті
Не обов'язкове до передачі поле (на вибір: USER, LOGIN, OWNER), що містить логін або e-mail або мобільний номер власника приладу в профілі учасника проекту для автоматичної реєстрації приладу. Передається у вигляді окремої метрики віртуального датчика з текстовим значенням. Враховується 1 раз для автоматичної прив'язки нічийних приладів до облікового запису в проекті і не підходить для зміни поточного власника приладу.
TCP/UDP:
#MAC
#OWNER#UserName
...
##
GET/POST:
ID=MAC&OWNER=UserName&...
Поля LAT,LON,ALT - широта, довгота, висота місця розташування приладу
Необов'язкові до передачі геокоординати місця знаходження пристрою моніторингу в десятковому вигляді!
Передаються окремими метриками віртуальних датчиків LAT, LON, ALT.
Може бути корисно для мобільних пристроїв моніторингу з GPS/ГЛОНАСС і підключеними до них датчиками.
TCP/UDP:
#MAC
#LAT#39.962502
#LON#-83.006104
#ALT#855
...
##
GET/POST:
ID=MAC&LAT=39.962502&LON=-83.006104&ALT=855...
Для GSM і WiFi приладів можна використовувати спеціальні метрики AP * і BS * для приблизного місця розташування по вишках стільникового зв'язку і / або точок доступу WiFi. Середня похибка 100м-10км, що значно точніше GeoIP.
Чим більше подібних метрик передасте в пакеті даних, тим точніше визначення місця розташування.
TCP/UDP:
WiFi BSSID = 00:00:00:00:00:00 и RSSI = -70:
#AP:00:00:00:00:00:00#-70
GSM MCC(000h) + MNC(000h) + LAC(0000h) + CID(0000000h) и RSSI = -50:
#BS:000:000:0000:0000000#-50
Поля mac1..mac - унікальні метрики датчиків, підключених до приладу
Призначені для ідентифікації датчиків і прив'язки їх показань до приладів.
Реєстрація всіх датчиків, підключених до приладу, відбувається автоматично при першій відправці їх показань на narodmon.ru.
Для датчиків температури сімейства DS18x20 метрика (серійний номер) являє собою 16 знаків 0-F.
Для інших датчиків рекомендується використовувати наступні метрики для автоматичного визначення типу даних(* - будь-яке число):
* Температура: T\d+, TEMP*, BMPT*, DHTT*, DSW*, DS18T*, BATTEMP
* Вологість: H\d+, RH, DHTH*, HUM, HUMID*
* Тиск: BMPP*, MMHG, HPA, PRESS, BAROM*
* Опади: RAIN, RAIN*
* Швидкість(вітер): WS, WS*, *KMH, *MPH, *SPD, WIND
* Азимут(напрямок): *DEG, *DIR
* Напруга: U*, V*, VOLT, VCC, UACC, VBAT, BATVOLT
* Сила струму: I*
* Потужність: P, P*, W, W*
* Електроенергія: WH, KWH, WH*, KWH*
* Водолічильники: WM, WM* (ХВП=CWM, ГВП=HWM)
* Освітленість: L*, LUX, LIGHT
* Радіація: R*, RAD
* Логічний(реле): S*, RL*, GPIO*, OUTPUT*, SIM*, RELAY
* Мережевий трафік: RX, TX, RX*, TX*
* Концентрація: CO, CO2, CO*, CH4, PPM
* Час(роботи): NOW, TIME, TIME, CURTIME, WORKTIME
* Сигнал(рівень): DBM, RSSI, WIFI, GSM, SIGNAL
* Індекс УФ: UV, UV*
* Заряд батареї: MB2BAT, BATCHARGE
* Пил(частинки): PM, PM*, DUST, SDS_P*
* Точка роси: DP, DP*, DEW
* Розташування: LAT, LON, ALT (широта, довгота, висота) розміщення датчиків.
Можна вказати в якості MAC назву датчика на латиниці без пробілів і знаків, але в цьому випадку тип даних доведеться вказати вручну в розділі Датчики.
TCP/UDP:
#MAC
#T1#00.00
...
##
GET/POST:
ID=MAC&T1=00.00&...
Поля value1..valueN - показання датчиків з точністю до сотих
Вкрай не рекомендується округляти покази, щоб не отримувати неправдиві повідомлення виходу з ладу датчика і щоб графік показів був більш читабельним, дискретність у DS18B20 = 0.0625С
Десяткові значення зі знаком з точністю до 0.01. Дробова частина відокремлюється крапкою, хоча кома теж допускається. Приклад показання: -13.54 або -13,54 або 760 (для атм. тиску).
Атмосферний тиск слід передавати у мм рт. ст. або в Па/гПа, в останньому випадку покази будуть автоматично конвертовані у мм рт. ст. для відображення на карті.
Мережевий трафік SNMP можна передавати як у Мбіт/с (Mbps) так і накопичений підсумок у байтах (октетах) вибравши тип датчика трафік, Rx/Tx буде перерахований автоматично в Mbps.
TCP/UDP:
#MAC
#T1#00.00
...
##
GET/POST:
ID=MAC&T1=00.00&...
Поля time1..timeN - час актуальності показів
Якщо покази датчиків передаються відразу після виміру, то даний параметр передавати не потрібно!
Необов'язкові до передачі цілочисельні 4х-байтові значення UnixTime або за стандартом ISO 8601.
Приклад: 1438772570 або 2015-08-05T14:03:11+03:00 або в hex вигляді 55C1ED5A (для економії).
При передачі UnixTime НЕ ТРЕБА додавати свій часовий пояс, так як він завжди по UTC+0.
Місцевий час передавати "як є" НЕ МОЖНА бо у сервера часовий пояс Europe/Moscow.
Час зняття показів потрібно передавати тільки у разі їх кешування перед відправкою або при масовому вивантаженні показів датчиків.
TCP/UDP:
#MAC
#T1#00.00#1737263863
...
##
GET/POST:
ID=MAC&T1=00.00&TIME=1737263863&...
Поля name1..nameN - назви датчиків
Необов'язкова до передачі назва датчика в кодуванні UTF-8 або Windows-1251 за фактом перейменування одноразово. Передається тільки в TCP/UDP після показання датчика і timeN(якщо зазначено).
Рекомендується для пристроїв з веб-інтерфейсом або з утилітою конфігурації, в яких можна вказати назви датчиків. У випадку, якщо даний параметр не порожній рядок і не є часом, то назва датчика на сервері змінюється на отримане від пристрою.
TCP/UDP:
#MAC
#T1#00.00#НазваДатчика
...
##
Передача показань по протоколах TCP/UDP на narodmon.ru:8283
Якщо Ваш пристрій допускає тільки введення IP адреси або у Вас проблеми з DNS, то використовуйте будь-який IP зі списку nslookup narodmon.ru до якого у Вас найменший ping, але пам'ятайте, що IP-адресу сервера може зміниться, а DNS-ім'я - немає. TCP також можна використовувати для масової завантаження показань на сервер "заднім числом" шляхом передачі в одному пакеті даних показань датчика в різні моменти часу, але не більше 4КБ пакет TCP і 512 байт для UDP. Переважно відправляти показання всіх датчиків в одному пакеті даних для мінімізації витрат на ініціалізацію з'єднання з сервером та імпорт показань датчиків.
Відповідь сервера при успішну відправку буде OK (або текст помилки або команда на виконання), що рекомендується використовувати в якості підтвердження одержання даних, а при відсутності відповіді повторити відправку коли відновиться зв'язок з сервером. При повідомленнях про помилки НЕ ПОВТОРЮВАТИ!
Кінець рядка відповіді сервера завершується спецсимволом \n 10 код(0A). Для оперативного відстеження стану логічних входів і виходів рекомендується у відповідь на отримання команди від сервера повертати новий стан логічних датчиків у вже відкритий раніше сокет згідно з протоколом, але тільки у разі змін щоб не отримати помилку малого інтервалу показань.
При використанні протоколу UDP відповіді сервера не піде.
| Три датчика реалтайм: #09-12-92-24-65-9D #T1#-19.05 #H1#24 #P1#695.87 ## | Формат пакета даних: #MAC[#NAME][#LAT][#LON][#ALT]\n #mac1#value1[#time1][#name1]\n ... #macN#valueN[#timeN][#nameN]\n ## |
| Завантаження історії показань: #09-12-92-24-65-9D #T1#-19.05#1737263863 #T1#20.72#1737263263 #T1#22.38#1737262663 ## | C назвою і координатами: #09-12-92-24-65-9D#Метео #OWNER#невідомий #T1#-19.05#Вулиця #T2#22.38#Будинок #P1#695.87#Барометр #LAT#39.962502 #LON#-83.006104 #ALT#705 ## |
\n - спецсимвол кінця рядка - код 10(0A).
## - ознака закінчення пакета даних (після нього розрив з'єднання), у [..] укладено необов'язковий параметр.
Приклад передачі показань по TCP на PHP
$fp = @fsockopen("tcp://narodmon.ru", 8283, $errno, $errstr);
if(!$fp) exit("ERROR(".$errno."): ".$errstr);
fwrite($fp, "#09-12-92-24-65-9D\n#T1#-19.05\n#H1#24\n#P1#695.87\n##");
fclose($fp);
Приклад передачі показань по TCP на Bash
#!/bin/bash
# by Tuinov Andrey voytmar @ yandex.ru
SERVER="narodmon.ru"
PORT="8283"
# MAC адреса пристрою. Замінити на свій!
DEVICE_MAC="A0B1C2D3E4F5"
# ідентифікатор пристрою, для простоти додається 01 (02) до MAC пристрої
SENSOR_ID_1=$DEVICE_MAC"01"
SENSOR_ID_2=$DEVICE_MAC"02"
# значення датчиків
sensor_value_1=20
sensor_value_2=-20.25
# встановлюємо з'єднання
exec 3<>/dev/tcp/$SERVER/$PORT
# відсилаємо одиничне значення датчика
printf "#%s\n#%s#%s\n##" "$DEVICE_MAC" "$SENSOR_ID_1" "$sensor_value_1" >&3
# відсилаємо множинні значення датчиків
#printf "#%s\n#%s#%s\n#%s#%s\n##" "$DEVICE_MAC" "$SENSOR_ID_1" "$sensor_value_1" "$SENSOR_ID_2" "$sensor_value_2" >&3
# отримуємо відповідь
read -r MSG_IN <&3
echo "$MSG_IN"
# закриваємо з'єднання
exec 3<&-
exec 3>&-
Приклад передачі показань по TCP на Python2
#!/usr/bin/env python2
# -*- coding: utf-8 -*-
# by Roman Vishnevsky aka.x0x01 @ gmail.com
import socket
# MAC адреса пристрою. Замінити на свій!
DEVICE_MAC = 'A0B1C2D3E4F5'
# ідентифікатор пристрою, для простоти додається 01 (02) до mac пристрої
SENSOR_ID_1 = DEVICE_MAC + '01'
SENSOR_ID_2 = DEVICE_MAC + '02'
# значення датчиків, тип float/integer
sensor_value_1 = 20
sensor_value_2 = -20.25
# створення сокета
sock = socket.socket()
# обробник винятків
try:
# підключаємося до сокету
sock.connect(('narodmon.ru', 8283))
# пишемо в сокет одиничне значення датчика
sock.send("#{}\n#{}#{}\n##".format(DEVICE_MAC, SENSOR_ID_1, sensor_value_1))
# пишемо в сокет множинні значення датчиків
# sock.send("#{}\n#{}#{}\n#{}#{}\n##".format(DEVICE_MAC, SENSOR_ID_1, sensor_value_1, SENSOR_ID_2, sensor_value_2))
# читаємо відповідь
data = sock.recv(1024)
sock.close()
print data
except socket.error, e:
print('ERROR! Exception {}'.format(e))
Приклад передачі показань по TCP на Python3 для Domotics
# Скрипт за допомогою модуля Пітона request і запиту json запитує
# дані обраного датчика у Domoticz і відправляє частину з них на
# сервіс Народний моніторинг (narodmon.ru)
# Автори tudimon, bigmak, Maker39 @ 4PDA
# підключаємо модулі
import requests
import socket
ip = '127.0.0.1' # ip-адреса Domoticz
port = '433' # порт
user = 'dz_user' # користувач Dz
password = 'dz_user_password' # пароль користувача
idx = 66 #номер датчика в Domoticz, який будемо опитувати
# Рядок запиту якщо потрібна авторизація
#get_url = 'http://'+user+':'+password+'@'+ip+':'+port+'/json.htm?type=devices&rid={}'.format(idx)
# Рядок запиту, якщо не потрібна авторизація
# у разі якщо скрипт виконується на тому ж пристрої, що і Dz і в
# Настройки - Настройки - Система
# Локальні мережі (без імені/пароля) вказано ip адреса
get_url = 'https://'+ip+'/json.htm?type=devices&rid={}'.format(idx)
# розкоментувати якщо потрібно рядок вивести в консоль для контролю
# print ('================================')
#print (get_url)
# print ('================================')
# запит даних обраного датчика
get_data = requests.get(get_url, verify=False).json()
# ключ verify=False довелося додати тому що у мене Dz працює тільки на 433 порту
# а SSL сертифікат самопідписаний, відповідно request лаявся на помилку сертифіката
# відповідь прийде у вигляді JSON, де необхідно вибрати цікавить поле,
# наприклад температура, вологість і рівень заряду батарейки
humidity = get_data['result'][0]['Humidity']
temperature = get_data['result'][0]['Temp']
batt_level = get_data['result'][0]['BatteryLevel']
# Виведемо дані в консоль pi
# коли скрипт налагоджений, наступні три рядки необхідно закоментувати
print ("Вологість" + str(humidity))
print ("Температура" + str(temperature))
print ("Заряд батарейки" + str(batt_level))
# ============== передача даних в сервіс narodmon ==================
# MAC адреса пристрою. Замінити на свій!
DEVICE_MAC = 'ffffffffffffff' # MAC dz Raspberry Pi
# ідентифікатор пристрою
SENSOR_ID_1 = 'dz_t'
SENSOR_ID_2 = 'dz_h'
# значення датчиків, тип float/integer
sensor_value_1 = temperature
sensor_value_2 = humidity
# створення сокета
sock = socket.socket()
# обробник винятків
try:
# підключаємося до сокету
sock.connect(('narodmon.ru', 8283))
# формуємо рядок для сокета при одиничному значенні датчика
#s_sock = ("#{}\n#{}#{}\n"##".format (DEVICE_MAC, SENSOR_ID_1, sensor_value_1))
# формуємо рядок для сокета при множинному значення датчиків
s_sock = ("#{}\n#{}#{}\n#{}#{}\n"##".format(DEVICE_MAC, SENSOR_ID_1, sensor_value_1, SENSOR_ID_2, sensor_value_2))
# Пишемо рядок з консоль для контролю
# ці три рядки після налагодження закоментувати
print('======================================')
print(s_sock)
print('======================================')
# Пишемо в сокет
sock.send(s_sock.encode('utf8'))
# читаємо відповідь
data = sock.recv(1024)
sock.close()
except socket.error as e:
print ('ERROR! Exception {}'.format(e))
Передача показань по протоколу HTTP GET/POST на http(s)://narodmon.ru/get (/post) i TLS шифрування
Рекомендується використовувати тільки у випадку, якщо доступ в Інтернет здійснюється через проксі-сервер, оскільки можливі проблеми з кеширующими проксі і вище ризик перехоплення / підміни даних без шифрування, а також збільшується час обробки даних в "години пік" з-за великої кількості відвідувачів сайту та мобільних клієнтів, що практично ніяк не впливає на наш протокол TCP/UDP (описаний вище). Максимальна довжина запиту до 4КБайт (4096 знаків).
Бажано надсилати свідчення всіх датчиків 1 запиті для мінімізації витрат на ініціалізацію з'єднання і обробку показань.
Відповідь сервера при успішну відправку буде OK (або текст помилки), що рекомендується використовувати в якості підтвердження одержання даних, а при відсутності відповіді повторити відправку коли відновиться зв'язок з сервером. При повідомленнях про помилки НЕ ПОВТОРЮВАТИ!
Шифрування: якщо ви підозрюєте, що вороги хочуть перехопити/підробити показання ваших датчиків, то слід використовувати в рядку адреси https://narodmon.ru/post і передавати дані з TLS шифруванням (SSL застарів).
Зразок запиту передачі показань методом HTTP GET
Слід знати, що це найпростіший спосіб для новачків, але небезпечний і ненадійний в плані легкості перехоплення/підробки даних без шифрування і залежно від навантаження на веб-сайті проекту і API для додатків. Максимальна довжина запиту 2 КБайт (2048 знаків).
Для включення TLS шифрування використовуйте адресу https://narodmon.ru/get?...
http://narodmon.ru/get?ID=MAC&mac1=value1&...&macN=valueN[&time=UnixTime][&name=назва][&owner=власник][&lat=широта][&lon=довгота][&alt=висота_над_морем]
Зразок запиту передачі показань методом HTTP POST
Слід знати, що надійність даного методу залежить від навантаження на веб-сайт проекту і API для додатків на відміну від TCP, UDP і MQTT.
Максимальна довжина запиту до 4 КБайт (4096 знаків). Для включення TLS шифрування використовуйте адресу https://narodmon.ru/post
POST http://narodmon.ru/post HTTP/1.0\r\n
Host: narodmon.ru\r\n
Content-Type: application/x-www-form-urlencoded\r\n
Content-Length: NN(кількість байт в рядку даних нижче)\r\n
\r\n
ID=MAC&mac1=value1&...&macN=valueN[&time=UnixTime][&name=назва][&owner=власник][&lat=широта][&lon=довгота][&alt=висота_над_морем]
Приклад передачі показань по HTTP POST на Python2
#!/usr/bin/env python2
# -*- coding: utf-8 -*-
# by Roman Vishnevsky aka.x0x01 @ gmail.com
import urllib2
import urllib
# MAC адреса пристрою. Замінити на свій!
DEVICE_MAC = 'A0B1C2D3E4F5'
# ідентифікатор пристрою, для простоти додається 01 (02) до mac пристрої
SENSOR_ID_1 = DEVICE_MAC + '01'
SENSOR_ID_2 = DEVICE_MAC + '02'
# значення датчиків, тип float/integer
sensor_value_1 = 28
sensor_value_2 = -12.34
# формування POST запиту для одиничного датчика
data = urllib.urlencode({
'ID': DEVICE_MAC,
SENSOR_ID_1: sensor_value_1
})
# формування POST запиту для 2х датчиків
# data = urllib.urlencode({
# 'ID': DEVICE_MAC,
# SENSOR_ID_1: sensor_value_1,
# SENSOR_ID_2: sensor_value_2
# })
# формування заголовків запиту
headers = {
'Content-Length': str(len(data)),
'Content-Type': 'application/x-www-form-urlencoded',
'Host': 'narodmon.ru'
}
# безпосередньо запит
request = urllib2.Request('http://narodmon.ru/post.php', data, headers)
response = urllib2.urlopen(request)
print response.headers
Приклад передачі показань на HTTP POST на PHP з cURL
$data = array('ID'=>'09-12-92-24-65-9D', 'T1'=>-19.05, 'H1'=>24, 'P1'=>695.87);
$ch = curl_init("http://narodmon.ru/post");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$reply = curl_exec($ch);
curl_close($ch);
Передача показань у форматі JSON протоколами TCP/UDP narodmon.ru:8283 або http(s)://narodmon.ru/json
Даний вид протоколу є найбільш функціональним і буде найбільш корисний для власників декількох приладів і для інтеграції з уже наявною системою моніторингу будинку або в офісі, тому що дозволяє в одному пакеті даних передати дані відразу з декількох пристроїв з усіма їх атрибутами позбавивши від великого обсягу ручної роботи почергової реєстрації та налаштування їх в проекті.
Передавати пакет даних можна як по протоколах TCP або UDP на порт narodmon.ru:8283, так і використовуватися HTTP(S) POST з шифруванням TLS або без нього на http(s)://narodmon.ru/json. обмеження за розміром пакета аналогічне іншим способам передачі: 4 КБайт (для UDP 512 байт через MTU).
Відповідь сервера при успішній відправці, помилку або при отриманні команд теж буде в форматі JSON, що рекомендується використовувати в якості підтвердження отримання даних, тобто при відсутності відповіді від сервера повторити відправку коли відновиться зв'язок. При повідомленнях про помилки не повторювати!
Приклади відповідей сервера:
{"error":"OK","errno":200} - дані успішно отримані, помилок немає;
{"error":"INTERVAL < 1 min","errno":429} - занадто часта відправка даних;
{"error":"JSON_ERROR_SYNTAX","errno":400} - дані отримані, але в них була помилка.
Формат переданих даних JSON
Нижче наведено приклад розгорнутої структури пакета JSON з усіма можливими параметрами при передачі показань датчиків (для економії трафіку можна записати все в 1 рядок і видалити зайві прогалини). Обов'язкові параметри виділені жирним, інші опціональні і їх рекомендуємо слати тільки при їх зміні. Після// вказані коментарі до параметрів, відправляти їх на сервер зрозуміло не потрібно.
{
"devices": [
{
"mac": "DEVICE_MAC", // унікальний для проекту серійний номер приладу;
"name": "DEVICE NAME", // назва приладу в кодуванні UTF-8;
"owner": "USERNAME", // логін або email або стільниковий власника приладу для автореєстрації;
"lat": 39.962502, // широта місця установки приладу;
"lon": -83.006104, // довгота місця установки приладу;
"alt": 978, // Висота над рівнем моря місця установки приладу;
"sensors": [
{
"id": "T1", // метрика датчика, унікальна для приладу;
"name": "SENSOR NAME", // назва датчика в кодуванні UTF-8;
"value": 00.00, // показання датчика;
"unit": "C", // одиниця виміру для датчика в UTF-8;
"time": 1737263863 // час актуальності показання датчика UnixTime(UTC+0);
},
{
// інші датчики на приладі
}
]
},
{
// інші прилади
}
]
}
Зразок передачі показань в JSON методом HTTP POST
Максимальна довжина запиту до 4 КБайт (4096 знаків).
Для включення TLS шифрування використовуйте адресу https://narodmon.com/json
POST http://narodmon.com/json HTTP/1.0\r\n
Host: narodmon.com\r\n
Content-Type: application/x-www-form-urlencoded\r\n
Content-Length: NN(кількість байт в рядку даних нижче)\r\n
\r\n
{ "devices": [{ "mac": "MAC", "sensors": [{ "id": "..", "value": 00.00 }, {..} ]}, {..} ]}
Передача показань у форматі InfluxDB по протоколу HTTP POST на http(s)://narodmon.com/post
Даний варіант передачі показань є розширенням протоколу HTTP POST для прошивок приладів з підтримкою часових рядів InfluxDB, наприклад luftdaten.info для вимірювання якості повітря (кількість частинок пилу).
В якості ID/MAC для реєстрації приладу в проекті слід використовувати значення вузла node.
Приклад формату (набір метрик датчиків може відрізнятися):
device,node=MAC SDS_P1=15.55,SDS_P2=6.57,BME280_temperature=6.37,BME280_pressure=99535.03,BME280_humidity=40.34,interval=300000,signal=-44
PS з докладним описом процедури підключення приладів з прошивкою luftdaten.info до нашого проекту ви можете ознайомитися в статті Олексія Надежина (ammo1) за що йому величезне спасибі!
Передача показань по протоколу MQTT на narodmon.ru:1883 (безкоштовно з обмеженнями)
При безкоштовному використанні сервер не підтримуватиме постійні (keep-alive) з'єднання, тобто. постійно скидатиме підключення після прийому пакета даних.
Даний спосіб передачі показань досить складний в реалізації і вимагає більш високий рівень технічної підготовки. Консультації та навчання по роботі з ним не проводяться і при виникненні проблем з його використанням краще перейдіть на більш прості протоколи описані вище. Використання цього протоколу виправдовує себе тільки зі складними пристроями зі зворотним зв'язком, де потрібна негайна реакція на команди з сервера.
MQTT (Message Queuing Telemetry Transport) – відкритий протокол, розроблений IBM спеціально для Інтернету речей і застосовується для обміну даними між пристроями. MQTT-мережа включає в себе MQTT-брокера, який служить посередником у взаємодії MQTT-агентів - видавців та підписників. Видавці публікують інформацію, призначену для підписників. Детальний опис протоколу викладено в специфікації MQTT Version 3.1.1.
MQTT є бінарним протоколом поверх TCP, що істотно скорочує обсяг переданих даних і вкрай корисно в нестабільних низькошвидкісних мобільних мережах. Крім того, з'єднання з брокером (сервером) ініціюється клієнтським пристроєм, що дозволяє працювати і з "сірими" IP адресами (за NAT провайдера), при цьому з'єднання з сервером як правило не рвуться (при стабільному каналі), що дозволяє максимально оперативно передавати показання датчиків і приймати команди на виконання з сервера.
При налаштуванні підключення MQTT до нашого брокера (серверу) слід вказати хост narodmon.ru порт 1883. Інтервал передачі стандартних показань як і для інших протоколів = 5 хв. При цьому ваш пристрій буде автоматично прив'язаний до вказаного вами облікового запису в проекті, якщо в CONNECT ви передали логін та пароль (або ваш код 0) у проекті. У випадку, якщо в налаштуваннях свого приладу ви вказали неправильний логін/пароль, ваш IP буде заблокований на 15 хвилин, після чого ви зможете повторити спробу.
CONNECT (код 1)
Підключення до сервера, необхідні параметри:
Ідентифікатор клієнта (ClientID) = MAC Вашего прибора
UserName = Ваш логін в проекті (якщо потрібна автозв'язка)
Пароль = Ваш пароль або ваш код 0 в проекті (якщо потрібна автозв'язка)
У відповідь відправляється CONNACK (код 2) з результатом:
0 - підключення успішно;
2 - недопустимий MAC приладу (ClientID);
3 - технический сбой брокера / недоступність СУБД;
4 - невірний логін або пароль (якщо вони передаються);
5 - в доступе показано (наприклад, із-за неуплати).
PUBLISH (код 3)
Публікація показаних датчиків, необхідні параметри:
Тема = логін/девайс/датчик (пример: username/devname/sensor1)
Значення = показание датчика.
У відповідь надсилається PUBACK (код 4) для QoS = 1 або PUBREC (код 5) для QoS = 2.
При використанні формату JSON:
Тема = логін/девайс/json (пример: username/devname/json)
Значення = показання всіх датчиків в одному рядку (пример: {"sensor1":1,"sensor2":2}).
PUBACK (код 4)
Підтвердження прийому даних клієнтом із QoS = 1 після команди PUBLISH (код 3) із сервера.
PUBREL (код 6)
Підтвердження прийому даних клієнтом із QoS = 2, відповідь на PUBREC (код 5).
У відповідь надсилається PUBCOMP (код 7).
SUBSCRIBE (код 8)
Передплата топики, команди UI та REST API.
У відповідь надсилається SUBACK (код 9).
Якщо вам потрібне відпрацювання підписки на топики інших приладів чи інших подій, то для розгляду можливості її впровадження пишіть у техпідтримку проекту з детальним описом вашого інформаційного обміну MQTT і бажаного функціоналу нашого брокера.
UNSUBSCRIBE (код 10)
Відписка від топіків. Нема дій.
У відповідь надсилається UNSUBACK (код 11).
PINGREQ (код 12)
Перевірка активності клієнта/сервера.
У відповідь надсилається PINGRESP (код 13).
DISCONNECT (тип 14)
Завершення сеансу з сервером, параметри не потрібні.