Device action
Seekers can request that a Provider takes an action. If the action is supported by the Provider, it should be acknowledged and performed, otherwise it should be ignored.
| Message Group Name | Value |
|---|---|
| Device action event | 0x04 |
| Device Action Code Name | Value |
|---|---|
| Ring | 0x01 |
Ringing a device
One use case for these actions is the Seeker requesting the Provider to ring, for example when a user has lost the device and needs to locate it. When the ring action is received, the Provider should begin playing a preloaded sound file at a high enough volume that the user is able to locate it. It is recommended that the sound be ramped from a low volume to max volume over time. Ringing should continue until an additional action is received directing a stop, or a timeout value has passed.
Additional data will be included in the message to indicate whether the ringing should be started or stopped, which can be expanded to support Providers with multiple components (a left and right bud). In the first byte, bits will be set to 1 to request a ring to start or 0 to request a ring to stop.
For example, if the first byte of additional data is set to:
- 0x00 (0b00000000): All components should stop ringing
- 0x01 (0b00000001): Ring right, stop ringing left
- 0x02 (0b00000010): Ring left, stop ringing right
- 0x03 (0b00000011): Ring both left and right
On Providers which do not support individual ringing, only 1 bit should be considered:
- 0x00 (0b00000000): Stop ringing
- 0x01 (0b00000001): Start ringing
The second byte in additional data, if present, represents the timeout in
seconds. This value should be used by the Provider to determine how long it
should ring before silencing itself. Based off of the ring right example above
and a timeout of 60 seconds, 0x013C would be passed as the additional data.
Syncing ringing status back to Seekers
Providers may want to notify a Seeker when it changes the ringing status, for example if a gesture causes the ringing to stop. The Seeker can then receive the message and update the UI if necessary.
The Provider should follow the same message format as defined in the example above. Seeker's will listen for this message and provide an acknowledgement when it is received.
Acknowledging an action
When an action is received, it should be acknowledged so that the Seeker knows whether or not the action was performed. If an acknowledgement is not received within 1 second of sending an action (or a negative-acknowledgement is received) the Seeker will assume the action is not currently supported.