Конектор на Edge

edge-connector.exe работи като Windows услугата EdgeConnector на компютър в мрежата на обекта. Изходен код: entrosity-edge-connector (cmd/edge-connector, пакети app, controllers, driver, spool, simui), който споделя entrosity-shared-go/agentkit (транспорт, изпълнител на задачи, хранилище за тайни с DPAPI, журнали, обвивка за услуга) с агента и конектора на Axis. Как се инсталира: Конектори.

Инсталиране

msiexec /i edge-connector.msi /qn ENROLLMENT_TOKEN=<token> SERVER_URL=https://hub.entrosity.com/edge

Свойство	Значение
ENROLLMENT_TOKEN	Токен за регистриране на конектор на Edge (Конектори → Инсталиране на конектор).
SERVER_URL	Адресът на Edge, включително /edge.

• Инсталира в %ProgramFiles%\Entrosity Edge Connector\ (64-битово, за машината) и регистрира услугата EdgeConnector (показвано име Entrosity Edge Connector, LocalSystem, автоматично стартиране, run) и източник в журнала Application със същото име.
• С двете свойства edge-connector enroll се изпълнява като SYSTEM, преди услугата да стартира; неуспешно регистриране връща инсталацията назад. На вече регистриран компютър не прави нищо и е успешно. Без свойствата услугата стартира и чака регистриране.
• След стартиране услугата се настройва да се рестартира 30 секунди след всеки от първите си три неуспеха, като броячът се нулира след денонощие (sc.exe failure, по възможност).
• Всяка инсталирана версия се заменя: с по-нов, същия или по-стар MSI (връщането към по-стара версия е позволено, за да може защитният механизъм на самообновяването да инсталира отново предишната версия). Директорията с данни се запазва, така че конекторът остава регистриран.
• Деинсталирането премахва услугата, connector.dat, state.json, controllers.json, останал от по-стари версии trackbase.json и опашката със събития (spool\, чиито събития принадлежат на премахнатия конектор); журналите се запазват.
• Подробен журнал на инсталацията (/l*v) съдържа токена: изтрийте го след това.

Команден ред

edge-connector <command> [flags]

  run         run the connector (foreground, or as a service under the SCM)
              --server URL --token T   enroll first if not enrolled yet
  enroll      enroll this machine: --server URL --token T [--force]
              (URL is the Edge address, e.g. https://hub.entrosity.com/edge)
  status      show enrollment state and events waiting for the server
  install     install the Windows service
  uninstall   remove the Windows service
  version     print the version

• enroll на регистриран компютър извежда already enrolled, освен ако не е подадено --force. Грешките назовават причината: токенът е невалиден (не е токен за конектор на Edge), няма оставащи използвания или е изтекъл или отменен.
• run без идентификационни данни и без --server/--token чака, като проверява на всеки 10 секунди, докато enroll не ги съхрани.
• status извежда enrolled: connector <id>, server <url> и events waiting for the server: <n>.
• Без команда извежда начина на използване, флаговете и променливите на средата.

Променливи на средата

Променлива	По подразбиране	Значение
EDGE_CONNECTOR_DATA_DIR	%ProgramData%\Entrosity Edge Connector (Windows), ~/.edge-connector другаде	Директория с данни.
EDGE_LOG_LEVEL	info	debug, info, warn или error.
EDGE_SIM_ADDR	127.0.0.1:9199	Адресът на страницата на симулатора; трябва да е loopback адрес. off я изключва.

За услугата задайте променливите като среда на услугата (HKLM\SYSTEM\CurrentControlSet\Services\EdgeConnector, стойност Environment, REG_MULTI_SZ) и я рестартирайте.

Файлове

%ProgramData%\Entrosity Edge Connector\
  connector.dat       credentials {connector_id, connector_key, server_url, ws_url},
                      encrypted with machine-scope DPAPI
  state.json          jobs in progress (reported as failed after a restart)
  controllers.json    each controller's target (with its PIN), driver, last applied
                      configuration (version, hash, snapshot), configurations that
                      failed part-way since ("attempts") and event cursor
  update\             self-update: the downloaded MSIs, the update script and its
                      outcome (see Self-update)
  spool\              the event queue: segments <first seq>.jsonl (4 MiB each)
                      and "acked" (the highest acknowledged sequence number)
  logs\connector.log  rotating log (the service also writes to the Application event log)

Директорията с данни се създава с права само за собственика. Извън Windows идентификационните данни се съхраняват некриптирани (само за разработка).

Драйвери

Драйвер	Състояние
simulator	Завършен: два симулирани контролера, съвместими с TrackBase002 (127.0.0.1:9001, 127.0.0.1:9002), и всеки друг адрес при първо използване; 2000 карти, 32 000 събития, решения при четене на карта по референтната семантика. Вижте Изпробване на Edge със симулатора.
trackbase002	Протоколът на контролерите на Track Access по TCP: проверка, търсене, конфигурация, събития, часовник, дистанционно отваряне и състояние (вижте по-долу). Серийните портове (RS-485) връщат unsupported. Още не е проверен с истински контролер.

Драйверите реализират един едър интерфейс (internal/driver): проверка, търсене, прилагане на цяла конфигурация, четене на събития след курсор, отваряне на врата, отчитане на състояние. С всяка конфигурация драйверът получава и конфигурациите, които контролерът може още да пази: последно приложената и всяка, която се е провалила по средата след нея (пазят се в controllers.json като attempts). Повторно изпращане на същата конфигурация (resync, Повторно изпращане на конфигурацията) изисква пълно презаписване.

trackbase002

Още не е проверен

Протоколът е възстановен чрез обратно инженерство от сървърния софтуер на производителя и още не е проверен с истински контролер. Всеки кадър се записва в журнала на ниво debug със скрит ПИН, така че запис на трафика може да го потвърди. Проверете го с един контролер, преди да преместите цял обект.

• Транспорт: само TCP, към host:port на контролера. Двоични кадри заявка/отговор (A … B, 37 или 264 байта) носят 32-битовия ПИН на контролера и 8-битова контролна сума; по една команда наведнъж за контролер. Конекторът държи по една връзка за контролер, отваря я с ръкостискане (което идентифицира контролера: фърмуерът се показва напр. като 0123 (type 02)) и я отваря отново след 1 минута бездействие или при грешка.
• ПИН кодове: задават се в Edge за всеки контролер (ПИН на контролера) и пристигат в целта на всяка задача за контролера (target.pin, Протокол на конектора на Edge). Конекторът пази целта с нейния ПИН в controllers.json и никога не връща ПИН кода обратно. trackbase.json, който по-старите версии четяха, се пренебрегва. Без ПИН контролерът е офлайн с грешката the controller's PIN is not set: set it in Edge (the controller's page, Controller PIN), а прилагането е неуспешно с config_rejected. При грешен ПИН контролерът не отговаря на ръкостискането: недостижим (check the controller's PIN).
• Търсенето няма ПИН кодове: адрес, който отговаря по TCP, се показва без фърмуера си; Проверка на връзката след добавянето му с неговия ПИН показва фърмуера.
• Нова цел (сменени в Edge ПИН, адрес, транспорт или адрес по шината) пристига като edge.config.apply на непроменената конфигурация: конекторът само обновява целта, без пълно презаписване.
• Конфигурация: картата се записва с една времева зона (от 16) и маска на четците. Всеки различен набор от графици става времева зона: най-много 16 на контролер, най-много 8 времеви прозореца на ден за всяка (прозорците на припокриващи се или съседни графици се обединяват). Номерата на картите са 24-битови: Wiegand 26 е код на обекта и номер; ключовете iButton трябва да се побират в 24 бита (6 шестнадесетични цифри). config_rejected назовава причината: карта с различни графици на различни врати, твърде много времеви зони или прозорци, ключ iButton над 24 бита, два идентификатора с един и същ 24-битов номер. Пълна памет: capacity_exceeded.
• Прилагане: контролерите не могат да изброяват или изчистват картите си, затова конекторът прилага разликата спрямо последно приложеното: изтрива премахнатите карти, презаписва променените времеви зони, записва новите и променените карти и потвърждава. Resync презаписва всяка времева зона и карта. Карти, записани извън Edge и липсващи в конфигурацията му, не се премахват.
• Празниците не могат да се съхранят: в празнични дни важат времената за делничните дни, а състоянието носи предупреждението holidays are not enforced by TrackBase controllers: weekday times apply on them. Четците iButton (четци 3 и 4) приемат всяка записана карта на всяка врата, както в софтуера на производителя; състоянието предупреждава, когато това има значение.
• Събития: четат се от журнала на събитията на контролера (кръгов буфер от 31 968 записа). Новоконфигуриран контролер се чете от текущата му позиция; по-старите събития не се внасят. Записите за карти стават access_granted, access_denied или unknown_card с врата, четец, посока и идентификатор. Записът не казва дали контролерът е отворил, затова конекторът определя типа по приложената конфигурация (която контролерът прилага), без празниците. Другите записи (температури, входове) се записват в журнала, но не се отчитат, докато форматът им не стане известен. След рестартиране събитията се четат, след като конфигурацията бъде приложена отново (автоматично, когато контролерът е онлайн; с нов опит всяка минута).
• Часовник: сверява се в часовата зона на конфигурацията, когато се разминава с повече от 2 секунди или е невалиден (някои контролери отчитат ден 00); проверява се при всяко свързване и четене на състоянието. След сверяването конекторът го прочита обратно с четене на състоянието; ако датата не е приета, опитва другите известни формати (ден от седмицата неделя = 0, понеделник = 0, BCD) и запазва този, който се прочита валиден. Ако нито един не се прочете валиден, на контролера остава форматът от протокола и се опитва отново след 10 минути. Ако друга програма сверява часовника (сървърът на производителя), конекторът го сверява отново при всяко четене: първо я спрете.
• Дистанционно отваряне: задейства релето на ключалката на вратата (Реле на ключалката на вратата, иначе реле N за врата N); контролерът го освобождава след собственото си време на релето, а времето за отключване, зададено в Edge, не се изпраща. Записва се събитие door_opened_remote.
• Състояние: онлайн или офлайн според четене на състоянието най-много на всеки 30 секунди. Състоянията отворена и заключена врата още не се отчитат (не е известно кои входове са контакти на вратите). Липсващ ПИН е текстът на грешката на контролера; ограниченията по-горе (празници, iButton четци) се показват в събитието config_applied.

Задачи и ленти

Лента	Задачи	Паралелност
config	edge.config.apply, edge.controller.remove	1 (шина с контролери се записва последователно)
door	edge.door.open	4 (никога зад конфигурация)
discover	edge.discover, edge.controller.test	1
update	update_agent (компонент edge-connector)	1

Payload-и и резултати: Протокол на конектора на Edge.

Интервали

Какво	Интервал
Сигнал за активност (heartbeat)	1 минута
Четене на събитията на всеки контролер	1 секунда
Отчет за състоянието на контролерите	1 минута и след всяка промяна
Качване на опашката със събития	Веднага щом пристигнат събития, иначе на всеки 5 секунди; при грешки нарастващо изчакване до 1 минута
Повторно изпращане на непотвърдена част по HTTP	15 секунди
Повторно свързване	Експоненциално нарастващо изчакване със случайно отклонение, както при агентите на Axis (Протокол)

Конекторът обявява възможностите access_control и edge_update (той инсталира самообновявания) в hello.

Самообновяване

Edge предлага по-нова версия на конектора като задача update_agent (component: edge-connector, Протокол на конектора на Edge); как изданията стигат дотам: Работа с Entrosity Edge.

1. Задачата носи изданието (target) и, когато Edge го има, MSI файла на работещата версия (rollback), всеки с подпис Ed25519 върху компонента, версията, SHA-256 и размера му. Конекторът проверява подписите с публичния ключ, вграден в него (RELEASE_PUBLIC_KEY при компилиране, -X …/agentkit/update.PublicKey=), преди да изтегли каквото и да е: компилация без ключа отговаря с update_unsigned, а грешен подпис – с signature_invalid.
2. Изтегля двата MSI файла по подписаните връзки от задачата (GET <адрес на Edge>/api/connector/v1/releases/{id}/msi?exp=&sig=, валидни 24 часа) в <директория с данни>\update\, проверява SHA-256 и размера им (download_failed, hash_mismatch) и регистрира еднократна планирана задача EdgeConnectorUpdate като SYSTEM, която стартира минута по-късно. Задачата завършва успешно с UpdateResult {scheduled, from_version, to_version, rollback}.
3. Планираната задача изпълнява msiexec /i <нов MSI> /qn. След това защитният ѝ механизъм изчаква (до пет минути) услугата EdgeConnector да работи и все още да работи минута по-късно; ако не работи, той инсталира отново предишния MSI (MSI пакетът позволява връщане към по-стара версия) и стартира услугата.
4. Резултатът се записва в журнала на конектора при следващото стартиране (self-update outcome, със състоянието и двете версии), а новата версия се отчита в hello.

Грешки на задачата: update_unsigned, signature_invalid, download_failed, hash_mismatch, exec_failed (папката за обновяване или планираната задача не могат да бъдат създадени), invalid_payload.

Конекторите, компилирани преди самообновяването, не обявяват edge_update и никога не получават обновления: обновете ги ръчно веднъж (Конектори → Обновления).