Define gear selection encoding; add Brake and Cruise Control buttons#18
Open
jonasbark wants to merge 2 commits into
Open
Define gear selection encoding; add Brake and Cruise Control buttons#18jonasbark wants to merge 2 commits into
jonasbark wants to merge 2 commits into
Conversation
Driven by manufacturer feedback on ambiguities in the button mapping: - 0x03 Gear Set: define the analog value as a direct 1-based gear index (0x02 = gear 1), not a percentage - 0x04 Chainring Set / 0x05 Cassette Set: new IDs for devices emulating NxM front/rear drivetrains, with guidance on coexisting with the flat 0x03 index via multi-action messages - 0x1A Brake: single analog braking axis (stronger lever wins on two-lever devices; 0x1B reserved for a future second axis) - 0x3C Cruise Control: digital toggle engaging at current power, with an optional absolute target encoded as value x 5 watts - Fix "Previous Internal" -> "Previous Interval" typo Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the OpenBikeControl protocol specification to formally define gear-selection analog encoding, introduce new drivetrain-specific gear selection IDs, and add two new riding controls (Brake and Cruise Control) to the standard button ID set.
Changes:
- Defined analog encoding for direct gear selection and added
0x04(Chainring Set) /0x05(Cassette Set) alongside0x03(Gear Set). - Added
0x1A(Brake) and0x3C(Cruise Control) with specified analog semantics. - Fixed a typo: “Previous Internal” → “Previous Interval” (
0x36) and updated the Python example’s button-name table with new IDs.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| PROTOCOL.md | Extends the protocol spec with defined analog encodings for gear selection, brake strength, and cruise control target power; adds new standard IDs and fixes a typo. |
| examples/python/protocol_parser.py | Adds new button IDs to the example parser’s BUTTON_NAMES mapping. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+153
to
+156
| **Cruise Control Analog Values:** | ||
| - `0x00` = Released | ||
| - `0x01` = Pressed — toggle cruise control on/off, engaging at the rider's current power | ||
| - `0x02-0xFF` = Engage cruise control with an absolute target power of value × 5 watts (`0x0A` = 50 W, `0x64` = 500 W, up to 1275 W) |
Comment on lines
+77
to
+81
| The analog value encodes a direct, 1-based gear position, offset by +1 so that the | ||
| values `0x00` and `0x01` keep their standard meaning: | ||
|
|
||
| - `0x00` = Released / no change | ||
| - `0x01` = Not used for gear selection (reserved) |
Comment on lines
+158
to
+160
| Most devices SHOULD simply send `0x01` and let the app capture the rider's current | ||
| power as the setpoint; subsequent adjustments use `0x30`/`0x31` (Increase/Decrease | ||
| Difficulty). The absolute form is intended for devices with their own target-power UI. |
Comment on lines
13
to
+17
| 0x01: "Shift Up", | ||
| 0x02: "Shift Down", | ||
| 0x03: "Gear Set", | ||
| 0x04: "Chainring Set", | ||
| 0x05: "Cassette Set", |
- Define cruise control absolute target range as 0x0A-0xFF with 0x02-0x09 reserved as no-op, removing the contradictory 50 W minimum wording - Clarify that gear-selection value 0x01 is a no-op for receivers instead of claiming it keeps its standard 'pressed' meaning - Use the Training Controls table names (Increase/Decrease Difficulty) for 0x30/0x31 consistently in the Multiple Actions example, parser, and README - Format gear selection (0x03-0x05) as a direct gear index and cruise control (0x3C) as target watts in format_button_state, with tests Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xb1g4o9rUri1NRC1DZUVb4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Addresses questions raised by a third-party equipment manufacturer about gear selection encoding and two missing riding controls.
Gear selection (0x03, new 0x04/0x05)
0x02= gear 1, up to 254 positions) — previously unspecified, and the generic analog semantics implied a percentage, which apps cannot decode without knowing the device's gear count.New buttons
0x01= full digital brake,0x02–0xFF= strength). Two-lever devices report the stronger lever;0x1Bis reserved for a second axis if front/rear braking ever becomes meaningful in apps.Misc
protocol_parser.pybutton name table; example tests pass.All changes are backward compatible: apps already ignore unknown button IDs, and the App Information message provides capability discovery for the new IDs.
🤖 Generated with Claude Code