Adopt the dedicated RS485 lock board as the only hardware adapter
维护者通常 1 天内回复
评估
这个 Issue 还没有评估数据。
描述
Summary
We want to simplify Open-Locker by making the dedicated RS485 electric-lock controller our only supported locker board and removing the generic Waveshare relay-board compatibility.
The dedicated adapter already exists in the locker client. This work should remove the Waveshare-shaped limitations around it, use the lock feedback returned directly after unlocking, and simplify installation and the Bill of Materials.
For operators and builders, the intended result is:
- fewer hardware components and cables
- easier board addressing through DIP switches
- direct lock feedback without a generic relay abstraction
- a much smaller configuration surface
- one clearly documented and tested reference setup
Product and protocol documentation:
https://de.aliexpress.com/item/1005004825186472.html
Technical background and current limitation
The locker client already contains a dedicated rs485_lock_board driver and adapter for the proprietary hexadecimal RS485 protocol with XOR/BCC validation, DIP addresses, unlock commands, and query-all status reads.
However, both production adapters currently implement the Waveshare-shaped LockerBusPort:
- actuation is named
flashRelay - a Waveshare-specific pulse duration is passed to every adapter
- actuation returns
Promise<void> - door feedback is exposed only through a later
readDoorSensorscall
The dedicated board already returns a feedback status (00 or 11) approximately 500 ms after an unlock command. The current codec validates this byte but deliberately discards it, so the application cannot use the board's direct feedback.
ADR-0061 explicitly preserves this behavior and must be superseded as part of the change.
Application and adapter changes
- Replace
flashRelaywith a protocol-neutral compartment unlock operation. - Return an optional post-actuation state observation from the hardware port.
- Map the dedicated board's unlock response through the configured feedback polarity:
door_closing:00 = open,11 = closeddoor_opening:11 = open,00 = closed
- Use that response as the first post-actuation state observation.
- Keep command acknowledgement and physical
opened/door_jammedevents separate. - Keep query-all polling for manual changes, uncommanded openings, and continued state observation.
- Keep
open,closed, andunknownas the application-facing state model. - Preserve actuation when the input already reports open, as required by #302.
- Remove the Waveshare adapter, native flash-register implementation, relay-specific startup failsafe, and
modbus-serialdependency when no longer used. - Remove Waveshare-only relay terminology from ports, tracing, logging, health reporting, tests, and documentation.
- Keep command deduplication because the board protocol has no transaction identifier.
Configuration and addressing
The production board uses fixed serial settings:
- 9600 baud
- 8 data bits
- no parity
- 1 stop bit
- no flow control
These values should live inside the dedicated adapter rather than remain operator-configurable.
The external hardware configuration should normally contain only the serial device path, preferably a stable /dev/serial/by-id/... path. Response timeout and reconnect policy should use documented internal defaults unless field experience demonstrates a need for operator configuration.
Also:
- remove
flashDurationMs - migrate the external
modbus:configuration to a minimal RS485/serial configuration - map backend
slaveIddirectly to the physical DIP address (1..31) - retain zero-based configured compartment addresses and translate them to one-based wire channels inside the adapter
- remove backend adapter selection after existing installations have a safe migration path
- coordinate backend and locker-client rollout so persisted runtime profiles and config hashes remain valid
Protocol and reliability requirements
- Continue validating XOR/BCC over every complete frame.
- Allow more than 500 ms for the delayed unlock response.
- Preserve serial transaction ordering and command priority.
- After timeout, malformed BCC, or excess input, discard buffered and late bytes before the next transaction.
- Do not infer query-all response length from a declared channel count. Decode the complete received frame and select only configured channels.
- Missing status bits must produce
unknown, not an incorrect state or process failure. - Treat DIP addresses
1..31as the supported range despite contradictory vendor text mentioning1..99. - Continue using query-all polling; unsolicited
0x82feedback requires customized firmware and is not part of the standard board. - Define timeout behavior for the case where the lock may have actuated but the response was lost.
- Verify recovery after USB-RS485 disconnect and reconnect without restarting the process.
- Keep full-open and multi-channel unlock commands out of the product interface unless a separate safety-reviewed use case requires them.
Hardware and Bill of Materials
Create one validated reference build based on:
- Raspberry Pi
- USB-to-RS485 adapter
- dedicated 8-channel RS485 lock-controller board
- compatible 12 V electric locks with the selected feedback type
- correctly sized 12 V power supply
- Raspberry Pi DC-DC converter
- XH2.54 lock/feedback cables
- RS485 and power wiring
Before simplifying the BOM, verify:
- whether the documented 6 A limit is total board current
- lock inrush current and safe simultaneous actuation limits
- flyback, short-circuit, overcurrent, reverse-polarity, ESD, and surge protection provided by the board
- whether the feedback contact represents the physical door position or only the latch/bolt state
- feedback polarity and contact bounce on the selected reference lock
- RS485 termination, biasing, grounding, and reliable multi-board daisy-chain wiring
- whether DIP-address changes require a power cycle
- how the physical full-open button is protected against accidental or unauthorized use
Remove the following from the minimal BOM only after validation:
- Waveshare
Modbus RTU Relay (D) - custom Open-Locker connection board
- connection-board terminal sets
- intermediate relay-board wiring
- external flyback components if the dedicated board is proven to provide adequate protection
Document the required XH2.54 harnesses explicitly; the product package includes only one lock cable.
Polling and scaling
The vendor's maximum of 31 boards does not guarantee that all boards can be queried every 500 ms at 9600 baud.
- Measure a complete polling cycle with the expected production board count.
- Define a supported maximum at the current polling interval, or distribute board queries across cycles.
- Ensure unlock commands retain priority over background polling.
- Run a sustained polling and actuation soak test on the production Raspberry Pi.
- Test at least two DIP-addressed boards on one physical RS485 bus before claiming multi-board production support.
Documentation and architecture decisions
- Create a new ADR that supersedes the applicable parts of ADR-0061 and the Waveshare hardware decision in ADR-0004.
- Review the startup, polling, reconnect, and direct-addressing ADRs for references that need superseding or clarification.
- Update the locker-client README and hardware integration documentation.
- Update English and German Bills of Materials.
- Update website hardware, architecture, and operations documentation.
- Document commissioning: stable serial path, DIP address, channel mapping, feedback type, and physical verification.
Acceptance criteria
- The dedicated RS485 board is the only production locker-board adapter.
- Unlocking no longer uses a Waveshare-shaped
flashRelayinterface. - The unlock response is mapped and used as the first post-actuation state observation.
- Command acknowledgement remains distinct from physical door-state events.
- Query-all polling still detects later and uncommanded state changes.
- External configuration is reduced to the values operators genuinely need.
- DIP address and channel translation are documented and tested.
- Invalid, truncated, delayed, and malformed frames cannot corrupt the next transaction.
- USB-RS485 disconnect and reconnect recover without a process restart.
- Multi-board polling and command priority are verified on real hardware.
- Power, protection, feedback semantics, and wiring are validated on the reference build.
- The minimal BOM no longer contains unnecessary Waveshare or connection-board components.
- Architecture and user-facing documentation describe the new reference hardware accurately.
- 主要语言
- PHP
- 星标
- 26
- 派生
- 2
- 平均合并
- 2 天 14 小时
- 30 天内合并 PR
- 14
环境准备
在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 没有贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
Open-Locker/Open-Locker 的其他 Issue
-
backend docs
难度 2/5 1-3 小时 新手友好度 67/100
Open-Locker/Open-Locker#368 ·
维护者通常 1 天内回复
-
iot client
难度 2/5 1-3 小时 新手友好度 82/100
Open-Locker/Open-Locker#365 ·
维护者通常 1 天内回复
-
docs
难度 2/5 1-3 小时 新手友好度 76/100
Open-Locker/Open-Locker#287 ·
维护者通常 1 天内回复
-
backend
难度 4/5 3-5 天 新手友好度 58/100
Open-Locker/Open-Locker#367 ·
维护者通常 1 天内回复
-
backend
难度 3/5 1-2 天 新手友好度 68/100
Open-Locker/Open-Locker#366 ·
维护者通常 1 天内回复
查看 Open-Locker/Open-Locker 的全部 Issue
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 78/100
Automattic/blocks-engine#4874 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
endoflife-date/endoflife.date#11561 ·
维护者通常 1 天内回复
-
area:php-extension priority:low type:bug
难度 2/5 1-3 小时 新手友好度 85/100
crazy-goat/go-mesi#623 ·
维护者通常 1 天内回复
-
good first issue priority:low type:bug
难度 2/5 1-3 小时 新手友好度 78/100
crazy-goat/fdb-php#184 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 75/100
nextcloud/groupfolders#5218 ·
维护者通常 1 天内回复