Усі посібники

Пояснення · 4 хв

Як працює обмежена команда

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

Що таке обмежена команда

Це одна команда потужності з чотирма полями: , потужність, тривалість і .

request
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.

Передумови

  1. Роль

    Надсилати можуть власник, адміністратор, розробник або оператор.

  2. Явний дозвіл

    власник або адміністратор увімкнув обмежене керування і підтвердив локальний запис. Кожне джерело починає в режимі лише спостереження.

  3. Живий конектор

    Для MQTT і Home Assistant: свіже рукостискання локального конектора, не старше 5 секунд, з увімкненим локальним записом.

  4. Свіжий і здоровий стан

    Телеметрія в межах свіжості, online, без аварій, якість даних GOOD, скінченні числа. Батарея має бути в спокої, з потужністю 0.

  5. Вільний слот

    Немає активної чи невизначеної команди. Не більше 5 нових команд на актив за хвилину.

ПричинаЩо означає
WRITE_PERMISSION_REQUIREDНемає дозволу на керування чи локальний запис.
STALE_OR_FUTURE_TELEMETRYДані застарілі або з майбутнього.
DEVICE_NOT_READYПристрій офлайн, має аварію або якість даних не GOOD.
RESTORE_BEFORE_COMMANDБатарея ще не в нулі.
POWER_LIMIT_EXCEEDEDПотужність поза межами.
SOC_OUTSIDE_BOUNDS, SOC_ENERGY_LIMIT_EXCEEDEDSOC уже поза межами або вийшов би за них за 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 поверне наявну команду. Новий ключ створюйте лише тоді, коли попередню команду точно завершено.