search

OpenTails / CRUMPET-Android

The Brains For Your Tail Company Gear!
GNU General Public License v3.0
31 stars 7 forks source link

missing protocol details #118

Closed MarcusWolschon closed 2 years ago

MarcusWolschon commented 3 years ago

Both protocol definitions are missing some important parts:

darkgrue commented 2 years ago

Working on putting together a major release for the next firmware revision. Updating the documentation will be part of that. I'll incorporate some of the suggestions below, but some I believe aren't in-scope:

Both protocol definitions are missing some important parts:

  • How to determine what protocol (ears or tail) and what version of the protocol a device speaks

Won't fix: Tails and ears are kinda self-evident.

The current protocol documents are correct across the current Production firmware, but with the introduction of OTA firmware updates, that will be changing. Upcoming revisions will probably note what commands are unique to the new firmware branche(s) and the FW version the command is introduced in.

  • How a device reacts to unsupported commands (e.g. sending a "BATT" command to a tail instead of ears)

Will add in upcoming version. (Responds with "ERR".)

  • service and characteristic UUIDs are missing in the protocol definitions and only found in source code (including the mentioned, separate battery characteristic of the EarGear)

Will consider in upcoming revision. However, it's documented in the repo readme on the front page, as well as in the Bluetooth serial console documentation in the Wiki.

  • Procedure to turn a command into a bytestream is not defined (newline/linefeed?, character set, endianess)

Won't fix. BLE protocol details are well outside of the scope of this documentation.

The firmware currently ignores trailing whitespace, to avoid issues between BLE library communication, and BLE terminal programs (which tend to send a CR/CRCLF).

  • Responses to commands (or the lack thereof) is not documented including the format of responses ("VER", "BATT")

Will add in upcoming version.

  • format of the documented, unrequested battery status updates is not documented

Some commands are used in development, or aren't user-facing and are currently undocumented. The app uses a BLE characteristic for battery information for the MiTail. Upcoming documentation updates should be more complete, however.

  • How to keep a connection open is not documented (device closes connection after a single command + response pair with no imediate next command being issued)

Won't fix. That's a problem with whatever you're using to communicate with the controller, there's nothing inherent in the protocol or implementation related to that.

MarcusWolschon commented 2 years ago

Procedure to turn a command into a bytestream is not defined (newline/linefeed?, character set, endianess) Won't fix. BLE protocol details are well outside of the scope of this documentation.

That is not BLE. Bluetooth Low Energy transports bytes. This is about turning strings into bytes.

MarcusWolschon commented 2 years ago

How to determine what protocol (ears or tail) and what version of the protocol a device speaks Won't fix: Tails and ears are kinda self-evident. Well, for a random Bluetooth device you have to somehow find out if that device is a tail or a pair of ears or neither.

darkgrue commented 2 years ago

That is not BLE. Bluetooth Low Energy transports bytes. This is about turning strings into bytes.

And that's a function of whatever method or BLE library you're using to send data, not the command protocol.

Well, for a random Bluetooth device you have to somehow find out if that device is a tail or a pair of ears or neither.

Still self-apparent. The product name is the broadcast device name not the command terminal, as specified in the documentation on the front page:

Device name is "(!)Tail1" (for DIGITAiL) or "mitail" for MiTail Device Service [0xffe0] (for DIGITAiL) Device Characteristic [0xffe1]

"EarGear" is the device name for the Ear Gear.

darkgrue commented 2 years ago

Wiki updated and Pull Request https://github.com/MasterTailer/CRUMPET/pull/129 created for Wiki images.