Protocol feedback

[mgibbs189]

Hey @jonasbark thanks for getting the ball rolling!

Overall this looks solid, but I do have a few suggestions / concerns:

• Are Social/Emotes and especially Power-ups really necessary? Kinda gimmicky for a protocol to officially support (unless in the custom/app-specific section)
• How did "Wave", "Thumbs up", "Bell" etc get chosen? But not things like "Hold my wheel", "Ease up", and "Next rider pull"? Would it be better to just have generic bytes (e.g. "Action 1", "Action 2", "Action 3") and let platforms decide on mapping? Or perhaps an "Open emotes panel" byte that displays some UI and users could then contextually use Navigation buttons to choose the action?
• How does one Start a workout? Same button ID as Pause? Or, same as Resume?
• What about Resetting (e.g. start over) or Clearing workouts?
• Perhaps Gear Shifting and Training could merge? 0x0 is a primo spot, shame that "Gear Shifting" takes up only 3/16 slots
• If more than 3 camera views are needed, then the button IDs would get out-of-order. Me being OCD, but maybe camera views could go last
• How would one start / stop / quit / save a ride?

Cheers

[jonasbark]

Thanks for taking the time to look it over and providing feedback!

Are Social/Emotes and especially Power-ups really necessary?

I don't disagree, but the goal would be to enable all available in-ride actions that a trainer app offers - and that includes these emotes from Zwift, MyWhoosh and others. Definitely won't be the default actions in the end, but good to have them nonetheless

Would it be better to just have generic bytes

Yes, definitely - good input! I think I'll make it similar to the analogue input, where you have a certain button ID and the value is the different action

How does one Start a workout? / What about resetting / clearing / etc

I would think it will be part of the "0x14 Select" button instead. You'd navigate the trainer UI with the directional (and contextual) buttons and start your workout (or pause) with the select button. Really depends on the trainer app UI, then.

Perhaps Gear Shifting and Training could merge? 0x0 is a primo spot, shame that "Gear Shifting" takes up only 3/16 slots

Can you clarify what you mean by that?

If more than 3 camera views are needed, then the button IDs would get out-of-order. Me being OCD, but maybe camera views could go last

True - that would also be a good candidate for analogue input

How would one start / stop / quit / save a ride?

See above - navigation the UI would make sense

[jedla22]

Hi @jonasbark , I’d like to add my two cents to this topic. First, I really want to appreciate the effort and energy you are putting into this initiative. Everyone involved in the indoor cycling industry knows that the situation around remote controls and related protocol standardization is far from ideal. There are a couple of different approaches, and some companies are even moving to closed protocols. So, we definitely need an open and widely adopted protocol. This may help speed up the development and adoption of different remote controls.

My comments on the proposal:

Based on my experience with different smart trainers and smart bike protocol implementations, I would propose simplifying the protocol and moving more responsibility to the application side.

The buttons for navigation (Up, Down, Right, Left), Select/Confirm, and Back/Escape look reasonable and are part of most gamepads as well. IMHO, it makes sense to make them part of the standard.

However, the rest of the buttons seem too specific to me. For example, the same physical button on a device can have different functionality based on context. For example, if the app is in simulation mode, a button might work as SHIFT UP, in ERG mode, it might work as ERG UP. Similarly, the button function for shifting can have different meanings based on the preferred shifting style—Shimano, SRAM, Campagnolo, or Sequential. The function of a particular button may be driven by the application context and user preferences. To be compatible with the proposed protocol, implementation on the device side would become much more complicated, or even impossible as the application context is usually unknown to remote controller.

IMHO, having just basic predefined buttons and then general action buttons that can be mapped to arbitrary functions would be more flexible.The protocol could provide some hints regarding which buttons are intended for shifting and which are intended to be general action buttons. It could also provide some metadata, like whether the device is an application (like a SwiftControl) or a BLE remote control (with one or two physical controls), etc.

Please let me know your thoughts.

[jonasbark]

Thanks Jan, that's valuable input, especially coming from the trainer apps perspective.

My focus was indeed too narrow, and I didn't fully grasp the many different in-game modes (workout, free ride, menu navigation, ...).

I'll give it more thought tomorrow and will update accordingly!

[jonasbark]

pull request is now available here:
#14

• (way) less predefined buttons, more general definitions
• the app information message now includes button names, especially useful for apps such as BikeControl, to show the users which actions the trainer app supports (aside from the predefined ones)
• device_type identifier added to the app information

[jonasbark]

@mgibbs189 @jedla22 I think I may have found a better alternative - let me know if you agree:

Let's imagine a hardware device with six buttons:

• 4 arrows:
  • in-game navigation, steering, menu navigation
• a plus button:
  • gear shifting, increase resistance, select
• a minus button:
  • gear shifting, increase resistance, back/cancel

Defining a generalized action with "usage hints" (such as shift up / select) has a few disadvantages:

• it leaves the implementation logic to the trainer app
• it is not clear how a button will be used
• it is not possible to have separate actions for a generalized action, if you have more buttons available

Here's my proposal: keep the list of more or less universal actions in the protocol, but allow the hardware (or software, such as BikeControl) to send multiple actions per button. E.g. the plus button sends three different actions simultaneously:

• 0x01 for shift up
• 0x30 for increasing resistance
• 0x14 for selecting in menus

This would also make it easy and very flexible to optionally remap the hardware buttons or your OpenBikeControl-compatible controller or gamepads, as we know which actions are supported by the trainer app (App Information Characteristic).

I'll create another PR with this, including the other feedback (consolidating enums (social, view controls) to an analog action)

EDIT: #16

[mgibbs189]

Here's some more examples.

1. Click v1 (2 buttons: plus, minus)
2. Click v2 (10 buttons: plus, minus, up, down, left, right, A, B, Y, Z)
3. Play / Kickr Bike Pro (12 buttons: plus, minus, steerLeft, steerRight, up, down, left, right, A, B, Y, Z)
4. Generic media controller (5 buttons: up, down, left, right, OK)
5. @jonasbark's example (6 buttons: up, down, left, right, plus, minus)
6. Steam Controller, haptics = 🤯

I tend to agree with @jedla22 here... the protocol having a narrow focus (raw inputs) and leaving it up to apps to handle the intentions / context.

Core mapping

Button ID	Action
0x01	Up
0x02	Down
0x03	Left
0x04	Right
0x05	A
0x06	B
0x07	Y
0x08	Z
0x09	Plus
0x0A	Minus
0x0B	OK
0x0C	Back
0x0D	Menu
0x0E	Home

...unfinished, see questions below.

• @jonasbark are you wanting to keep this cycling-specific? Or is the idea to be a general-purpose button / controller open standard?
• Not sure how to handle steering. Separate button IDs? Or lumped with Left/Right? How to handle haptic support?
• What about (PS5 / Steam Controller) joystics? I.e. a module w/ both haptic and button-press elements?
• Current thinking is to have Core mapping in 0x0, Extra buttons in 0x2, and Extra haptics in 0x4.

[jonasbark]

A wall of text incoming, but it's important to get it right!
Let me explain the two main reasons why the protocol was created:

---

1) no existing standard for Bluetooth hardware devices acting as "Controllers"

Currently, there's a huge number of different input devices that could be used to control trainer apps. Gamepads, keyboards, HID controllers, ... and it's up to the trainer apps to support these devices. Many trainer apps do not.

Then there's a small number of dedicated controllers (such as Zwift Clicks, CYCPLUS BC2) and a small number of controllers built into bikes (e.g. Wahoo Kickr Bike Shift). They use their own proprietary protocol. Some trainer apps support these, and again, many do not (for good reasons).

Hence the need for a dedicated protocol that can be implemented in future hardware devices, but also into other apps that can therefore control the trainer app by acting as bluetooth device (such as BikeControl).

You could make the argument to reuse the existing HID protocol, but this one has a few issues:

• only apps in the foreground get the input events - no shifting would take place if you show e.g. YouTube in the foreground
• some HID keys are intercepted by the operating system
• the HID profile cannot be emulated by apps
• it's not flexible enough: to work well with the "other apps" the trainer app should report its supported actions (or keys)

---

2) no proper way to control trainer apps on the same device or on the same network

Apps such as BikeControl cannot officially control actions on trainer apps. To do this right now, BikeControl uses different methods to achieve this:

• on the same device you can send keyboard inputs (if the trainer app supports them, and only on Desktop devices) or touch input (only Android and only using sensitive permissions)
• on other devices BikeControl acts as Bluetooth or Network controller by emulating a supported device

Needless to say both of these methods are troublesome and very limited on some platforms such as iOS, macOS and even Windows.

---

Given that let's go back to the argument of raw input vs dedicated actions. Here are some reasons against raw inputs, some of which only valid for use cases such as BikeControl:

• raw inputs leave the implementation logic to the trainer app, which can result in unexpected actions taking place across different trainer apps. Especially when a single raw input has a different meaning depending on the context.
• having a limited amount of raw inputs seems to be an unnecessary constraint
• in BikeControl I want to offer full customization to each controller button or input event (such as Di2 shifting events): the user should be able to select from an easy-to-understand list of actions that will be triggered. Offering "A", or "Y" would not be suitable, even with the "usage hints"

With raw inputs you'd eventually end up copying the HID profile.

Therefore, I really prefer the idea of dedicated "intentions", as it achieves:

• full customizability for both, hardware controllers, and "software controllers"
• easy to understand for the user, especially as trainer apps list the supported intentions (as opposed to supported raw inputs) via the App Information Characteristic
• enforces the same implementation across different trainer apps, which is especially important when designing dedicated hardware
• I'd like to offer a way for the user to update the button "intentions" directly on the hardware's firmware. Then trainer apps won't need to support any customization options - they "just" need to support a good amount of "intentions"

---

are you wanting to keep this cycling-specific? Or is the idea to be a general-purpose button / controller open standard?

Yes, at least version 1 of the protocol solely focuses on Bike trainer apps. Some trainer apps support treadmill running as well and if there's demand, dedicated actions for these use cases could be added in a later version.

Not sure how to handle steering. Separate button IDs? Or lumped with Left/Right? How to handle haptic support?

That would be solved by the "Intentions". The tricky part can be when the trainer app offers a navigation option at crossroads but this could be solved by e.g. only doing steering when the button is pressed for a longer time

What about (PS5 / Steam Controller) joystics? I.e. a module w/ both haptic and button-press elements?

Do you mean analog input? Analog input values are also covered by the protocol as part of the "button state" :)

[mgibbs189]

Regardless of the protocol details, the path to adoption starts by building a prototype hardware controller. That's presumably something you're already thinking about 👍

@jonasbark I see a few BikeControl mentions in your reasoning. In a "perfect" world where all platforms adopt an open controller standard, wouldn't that render BikeControl obsolete? Is that your goal?

[jonasbark]

Indeed, hardware is the next step!

wouldn't that render BikeControl obsolete? Is that your goal?

If everyone owned hardware built on top of the OpenBikeProtocol, then indeed BikeControl would at some point be less and less desirable.
However, that is ultimately what the user and the companies behind the trainer apps want: a way to control the trainer app officially and directly without anything in between. And I'm happy to pave that path.