Dokumentacja boneIO | Dodawanie urządzenia Modbus

Ten przewodnik wyjaśnia, jak dodać obsługę nowego urządzenia Modbus (czujnika, licznika energii itp.) do boneIO Black. Definicja urządzenia jest przechowywana jako plik JSON, który opisuje jak odczytywać i interpretować rejestry Modbus.

Aplikacja webowa - Kreator urządzeń

Najłatwiejszym sposobem na utworzenie definicji urządzenia Modbus jest użycie wbudowanego Kreatora urządzeń Modbus w interfejsie webowym.

Dostęp do kreatora

Otwórz interfejs webowy boneIO
Przejdź do sekcji Modbus Helper
Wybierz zakładkę Creator

Modbus Device Creator

Informacje o urządzeniu

Opcja	Opis
Nazwa modelu	Nazwa modelu urządzenia wyświetlana w Home Assistant (np. "SHT30 Czujnik temperatury i wilgotności")
Nazwa pliku	Nazwa pliku JSON (np. "sht30"). Jeśli pusta, zostanie wygenerowana z nazwy modelu
Kategoria	Kategoria urządzenia: `sensors`, `energy_meters`, `hvac`, `inverters` lub `other`
Adres urządzenia testowego	Adres Modbus podłączonego urządzenia do testowania rejestrów

Dodawanie rejestrów

Kliknij Dodaj rejestr, aby zdefiniować każdy punkt danych do odczytu z urządzenia.

Opcja	Opis
Nazwa	Nazwa czujnika wyświetlana w Home Assistant
Adres	Adres rejestru Modbus (sprawdź dokumentację urządzenia)
Typ rejestru	Rejestr `holding` lub `input`
Jednostka	Jednostka miary (np. °C, %, V, A, kWh)
Typ wartości	Typ danych - zobacz tabelę poniżej
Klasa urządzenia	Klasa urządzenia Home Assistant (temperature, humidity, voltage, itp.)
Klasa stanu	`measurement`, `total` lub `total_increasing`

Typy wartości

Typ	Opis	Rozmiar
U_WORD	Liczba całkowita 16-bit bez znaku	1 rejestr
S_WORD	Liczba całkowita 16-bit ze znakiem	1 rejestr
U_DWORD	Liczba całkowita 32-bit bez znaku (Big Endian)	2 rejestry
S_DWORD	Liczba całkowita 32-bit ze znakiem (Big Endian)	2 rejestry
U_DWORD_R	Liczba całkowita 32-bit bez znaku (Little Endian)	2 rejestry
S_DWORD_R	Liczba całkowita 32-bit ze znakiem (Little Endian)	2 rejestry
FP32	Liczba zmiennoprzecinkowa 32-bit (Big Endian)	2 rejestry
FP32_R	Liczba zmiennoprzecinkowa 32-bit (Little Endian)	2 rejestry
U_QWORD	Liczba całkowita 64-bit bez znaku	4 rejestry
S_QWORD	Liczba całkowita 64-bit ze znakiem	4 rejestry

Filtry

Filtry pozwalają przekształcać surowe wartości rejestrów. Kliknij przycisk + obok "Filtry", aby dodać:

Multiply - Pomnóż wartość (np. 0.1 aby przekonwertować 245 → 24.5°C)
Offset - Dodaj/odejmij wartość

Testowanie rejestrów

Przed zapisaniem możesz przetestować każdy rejestr klikając przycisk ▶. Odczytuje to rzeczywistą wartość z podłączonego urządzenia, aby zweryfikować poprawność konfiguracji.

Konfiguracja Set Base (opcjonalna)

Włącz te opcje, jeśli urządzenie obsługuje zmianę adresu Modbus lub prędkości transmisji:

Opcja	Opis
Włącz zmianę adresu	Urządzenie obsługuje zmianę adresu Modbus
Rejestr adresu	Adres rejestru do zapisu nowego adresu Modbus
Włącz zmianę baudrate	Urządzenie obsługuje zmianę prędkości transmisji
Rejestr baudrate	Adres rejestru do zapisu prędkości transmisji
Mapowania baudrate	Mapowanie prędkości na wartości rejestru (np. 9600 → 0, 19200 → 1)

Eksportowanie

Pokaż podgląd JSON - Podgląd wygenerowanej konfiguracji
Kopiuj JSON - Skopiuj do schowka
Pobierz JSON - Pobierz jako plik

Struktura pliku JSON

Definicje urządzeń są przechowywane w katalogu boneio/modbus/devices/<kategoria>/.

Przykładowa konfiguracja

sht30.json

{
  "model": "SHT30 Czujnik temperatury i wilgotności",
  "set_base": {
    "set_address_address": 256
  },
  "registers_base": [
    {
      "base": 1,
      "length": 2,
      "register_type": "holding",
      "registers": [
        {
          "name": "Temperatura",
          "address": 1,
          "unit_of_measurement": "°C",
          "state_class": "measurement",
          "device_class": "temperature",
          "value_type": "S_WORD",
          "filters": [
            { "multiply": 0.1 }
          ]
        },
        {
          "name": "Wilgotność",
          "address": 2,
          "unit_of_measurement": "%",
          "state_class": "measurement",
          "device_class": "humidity",
          "value_type": "S_WORD",
          "filters": [
            { "multiply": 0.1 }
          ]
        }
      ]
    }
  ]
}

Zmienne konfiguracyjne

Poziom główny

Zmienna	Wymagana	Opis
model	Tak	Nazwa modelu wyświetlana w Home Assistant
set_base	Nie	Konfiguracja zmiany adresu/baudrate urządzenia
registers_base	Tak	Tablica bloków rejestrów

set_base

Zmienna	Opis
set_address_address	Adres rejestru do zapisu nowego adresu Modbus
set_baudrate.address	Adres rejestru do zapisu prędkości transmisji
set_baudrate.possible_baudrates	Mapowanie prędkości na wartość rejestru

registers_base (Blok)

Zmienna	Opis
base	Początkowy adres rejestru dla tego bloku
length	Liczba rejestrów do odczytu w jednym żądaniu
register_type	`holding` lub `input`
registers	Tablica definicji rejestrów

registers (Pojedynczy rejestr)

Zmienna	Wymagana	Opis
name	Tak	Nazwa czujnika w Home Assistant
address	Tak	Adres rejestru
unit_of_measurement	Tak	Jednostka (°C, %, V, A, itp.)
state_class	Tak	`measurement`, `total` lub `total_increasing`
device_class	Nie	Klasa urządzenia HA
value_type	Tak	Typ danych (zobacz tabelę Typy wartości)
filters	Nie	Tablica filtrów do zastosowania

Udostępnianie swojego urządzenia

Po utworzeniu i przetestowaniu definicji urządzenia:

Zrób fork repozytorium boneIO
Dodaj swój plik JSON do odpowiedniego folderu:
- boneio/modbus/devices/sensors/ - czujniki (temperatura, wilgotność, odległość)
- boneio/modbus/devices/energy_meters/ - liczniki energii
- boneio/modbus/devices/hvac/ - klimatyzacja, wentylacja
- boneio/modbus/devices/inverters/ - falowniki
- boneio/modbus/devices/other/ - inne urządzenia
Utwórz Pull Request

Twój wkład pomoże innym użytkownikom z tym samym urządzeniem!

Dodawanie urządzenia Modbus

Na tej stronie