Пояснення · 4 хв
Як працює обмежена команда
Обмежена команда просить пристрій ненадовго змінити потужність у чітких межах, а потім повернутися назад. Кожен крок має окремий доказ.
Що таке обмежена команда
Це одна команда потужності з чотирма полями: Унікальний ключ запиту. Повторне надсилання з тим самим ключем не створює другу команду.Детальніше в посібнику →, потужність, тривалість і Скільки секунд команда лишається чинною. Прострочену команду пристрій не виконує.Детальніше в посібнику →.
POST /v1/lab/assets/{asset_id}/commands
{
"idempotency_key": "3f0c2a7e-5b1d-4c39-9a51-2b6f0e8d7c10",
"power_kw": 0.5,
"duration_seconds": 10,
"ttl_seconds": 15
}Еталонна перевірка для батареї: +0,5 кВт протягом 10 секунд з TTL 15 секунд, потім повернення до нуля. Для навантаження: базове споживання -5 кВт, скорочення до -3 кВт, потім виміряне повернення до бази.
Знак: для батареї плюс — розряд, мінус — заряд. Для навантаження споживання від’ємне.
Межі
power_kw приймається від -10 до 10 кВт. Далі діє найсуворіша з меж: загальна межа Lab, межі профілю і локальна межа джерела.
Для батареї потужність також не більша за доступну потужність заряду чи розряду. SOC має бути в межах профілю. Lab рахує енергію на весь TTL, а не лише на тривалість, і перевіряє, що SOC лишиться в межах.
Для навантаження ціль має бути між нижньою і верхньою межею споживання. Сервер також перевіряє мінімальний час увімкнення і вимкнення.
Тривалість і TTL
duration_seconds — скільки триває зміна. ttl_seconds — скільки команда лишається чинною. Обидва від 1 до 60 секунд у межах профілю. Тривалість не може бути більшою за TTL.
Після тривалості пристрій повертається назад. Після TTL команда вже не може бути виконана. Локальний сторож конектора працює незалежно від зв’язку і повертає пристрій при розриві, відкликанні дозволу, збої, завершенні тривалості чи TTL.
Ключ ідемпотентності
idempotency_key — від 1 до 128 символів: латинські літери, цифри та . _ : -. Ключ унікальний для активу.
Той самий ключ з тим самим запитом повертає ту саму команду, а не нову. Той самий ключ з іншим запитом дає 409.
Передумови
Роль
Надсилати можуть власник, адміністратор, розробник або оператор.
Явний дозвіл
власник або адміністратор увімкнув обмежене керування і підтвердив локальний запис. Кожне джерело починає в режимі лише спостереження.
Живий конектор
Для MQTT і Home Assistant: свіже рукостискання локального конектора, не старше 5 секунд, з увімкненим локальним записом.
Свіжий і здоровий стан
Телеметрія в межах свіжості, online, без аварій, якість даних GOOD, скінченні числа. Батарея має бути в спокої, з потужністю 0.
Вільний слот
Немає активної чи невизначеної команди. Не більше 5 нових команд на актив за хвилину.
| Причина | Що означає |
|---|---|
| WRITE_PERMISSION_REQUIRED | Немає дозволу на керування чи локальний запис. |
| STALE_OR_FUTURE_TELEMETRY | Дані застарілі або з майбутнього. |
| DEVICE_NOT_READY | Пристрій офлайн, має аварію або якість даних не GOOD. |
| RESTORE_BEFORE_COMMAND | Батарея ще не в нулі. |
| POWER_LIMIT_EXCEEDED | Потужність поза межами. |
| SOC_OUTSIDE_BOUNDS, SOC_ENERGY_LIMIT_EXCEEDED | SOC уже поза межами або вийшов би за них за TTL. |
| INVALID_DURATION_OR_TTL | Тривалість чи TTL поза межами, або тривалість більша за TTL. |
| MINIMUM_ON_OFF_NOT_MET | Навантаження перемикалося надто недавно. |
Окремі докази
REQUESTED і ACCEPTED — факти хмари: запит прийнято до розгляду. Далі кожен етап доводить окреме і має своє джерело.
| Етап | Що він доводить |
|---|---|
| ACKNOWLEDGED | Конектор чи симулятор прийняв команду. Потужність ще могла не змінитися. |
| EXECUTED | Уставку справді записано в пристрій. |
| MEASURED | Окреме канонічне спостереження показало нову потужність. |
| RESTORE_EXECUTED | Команду повернення записано в пристрій. Їй передує RESTORE_REQUESTED. |
| RESTORED | Окреме спостереження показало повернення: 0 для батареї, виміряну до команди потужність для навантаження. |
Етап не може замінити інший. Вимір не заміняє підтвердження, а PUBACK брокера не є доказом виконання. Якщо стан відсутній чи недійсний, команда стає UNKNOWN і блокує нові команди.
Докази можна експортувати як маніфест із SHA-256. Він позначений LAB, production_eligible false і physical_qualification UNVERIFIED.
Скасування
POST /v1/lab/assets/{asset_id}/commands/{command_id}/abort просить зупинити активну команду. Вимкнення керування робить те саме для всіх активних команд.
Прийняте скасування — це ще не повернення. Чекайте RESTORED і виміряної потужності повернення.
Чому немає автоматичних повторів
Таймаут не означає відмову. Пристрій міг уже змінити потужність. Автоматичний повтор міг би застосувати команду двічі.
Тому Lab публікує кожен ненульовий кадр лише раз. Після перепідключення чи перезапуску завершена команда не повторюється. Збережена ненульова уставка ніколи не відновлюється.
Якщо відповідь невизначена, спершу перегляньте історію команд. Щоб повторити безпечно, надішліть той самий запит з тим самим ключем: Lab поверне наявну команду. Новий ключ створюйте лише тоді, коли попередню команду точно завершено.