# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Running Speed and Cadence Service (0x1814): a foot pod for running apps.
Serve it and send the speed and cadence you measure::
from bledev.runningspeed import RunningSpeedCadence
pod = RunningSpeedCadence(stride_length=True, total_distance=True, running_status=True)
ble.register_services(pod.service)
connection = await ble.advertise(name="Pod", services=[pod.SERVICE])
pod.update(2.9, 168, stride_m=1.04, distance_m=1250.0, running=True)
Speed is in metres per second and cadence in steps per minute. Pass
``stride_m``, ``distance_m`` or ``running`` only if you created the pod to
report them: the service sets the measurement's flags from what you send, and
its Feature characteristic tells the app which to expect.
The SC Control Point lets a central set the total distance and ask for the
supported sensor locations. It answers with indications, so run
``asyncio.create_task(pod.run())`` beside your loop and have the central
subscribe to them. Give ``on_set_cumulative`` a function that takes the new
total distance in metres to accept a Set Cumulative Value; without one the
service answers "op code not supported". On CircuitPython an indication goes
out but its acknowledgement isn't reported (see `bledev.cpble`).
``ble.register_services()`` replaces whatever was registered before, so pass
this service together with the others. Any peripheral backend serves it:
MicroPython (`bledev.mpble`), CircuitPython (`bledev.cpble`) and the fake one
for tests.
"""
import struct
from . import Characteristic, Service, UUID
from ._sig import (
INVALID_PARAMETER,
OP_CODE_NOT_SUPPORTED,
SET_CUMULATIVE_VALUE,
SUCCESS,
check_location,
serve_control_point,
)
SERVICE = UUID(0x1814)
RSC_MEASUREMENT = UUID(0x2A53)
RSC_FEATURE = UUID(0x2A54)
SENSOR_LOCATION = UUID(0x2A5D)
SC_CONTROL_POINT = UUID(0x2A55)
# Feature bits.
_FEATURE_STRIDE = 0x01
_FEATURE_DISTANCE = 0x02
_FEATURE_STATUS = 0x04
_FEATURE_MULTIPLE_LOCATIONS = 0x10
# Measurement flags.
_STRIDE = 0x01
_DISTANCE = 0x02
_RUNNING = 0x04
REQUEST_SUPPORTED_LOCATIONS = 0x04
RESPONSE = 0x10
[docs]
def encode_measurement(speed_mps, cadence, stride_m=None, distance_m=None, running=None):
"""The RSC Measurement bytes: speed in 1/256 m/s, cadence, stride in cm, distance in 1/10 m.
``running`` is True for running, False for walking, None to leave the
status out.
"""
speed = int(speed_mps * 256 + 0.5)
if not 0 <= speed <= 0xFFFF:
raise ValueError("a speed is 0 to 255 m/s")
cadence = int(cadence)
if not 0 <= cadence <= 0xFF:
raise ValueError("a cadence is 0 to 255 steps per minute")
flags = 0
out = struct.pack("<HB", speed, cadence)
if stride_m is not None:
flags |= _STRIDE
out += struct.pack("<H", int(stride_m * 100 + 0.5) & 0xFFFF)
if distance_m is not None:
flags |= _DISTANCE
out += struct.pack("<I", int(distance_m * 10 + 0.5) & 0xFFFFFFFF)
if running:
flags |= _RUNNING
return bytes((flags,)) + out
[docs]
class RunningSpeedCadence:
"""A Running Speed and Cadence Service.
Args:
stride_length: True if the pod reports stride length.
total_distance: True if it reports total distance.
running_status: True if it says whether the wearer is walking or running.
location: A Sensor Location number (see `bledev._sig.LOCATIONS`), or None
to leave out the Sensor Location characteristic.
locations: The locations the sensor can be set to, when it supports more
than one.
on_set_cumulative: ``f(distance_m)`` called when a central sets the total
distance; return False to refuse.
"""
SERVICE = SERVICE
def __init__(self, stride_length=False, total_distance=False, running_status=False,
location=None, locations=(), on_set_cumulative=None):
self._have = (bool(stride_length), bool(total_distance), bool(running_status))
self._on_set_cumulative = on_set_cumulative
self._locations = tuple(check_location(x) for x in locations)
self.service = Service(SERVICE)
#: The RSC Measurement `bledev.Characteristic`: notify only.
self.characteristic = Characteristic(self.service, RSC_MEASUREMENT, notify=True, initial=bytes(4))
feature = (
(_FEATURE_STRIDE if stride_length else 0)
| (_FEATURE_DISTANCE if total_distance else 0)
| (_FEATURE_STATUS if running_status else 0)
| (_FEATURE_MULTIPLE_LOCATIONS if self._locations else 0)
)
Characteristic(self.service, RSC_FEATURE, read=True, initial=struct.pack("<H", feature))
if location is not None:
Characteristic(self.service, SENSOR_LOCATION, read=True, initial=bytes((check_location(location),)))
self._control = None
# The control point is required for total distance or several locations.
if total_distance or self._locations:
self._control = Characteristic(
self.service, SC_CONTROL_POINT, write=True, indicate=True, capture=True, max_len=20
)
[docs]
def update(self, speed_mps, cadence, stride_m=None, distance_m=None, running=None):
"""Send a measurement to every central subscribed to it.
Args:
speed_mps: Instantaneous speed in metres per second.
cadence: Steps per minute.
stride_m: Instantaneous stride length in metres.
distance_m: Total distance in metres.
running: True when running, False when walking.
"""
stride, distance, status = self._have
if (stride_m is not None and not stride) or (distance_m is not None and not distance) or (
running is not None and not status
):
raise ValueError("this pod was not created to report that")
self.characteristic.write(encode_measurement(speed_mps, cadence, stride_m, distance_m, running), True)
def _handle(self, opcode, parameter):
if opcode == SET_CUMULATIVE_VALUE and self._have[1] and self._on_set_cumulative is not None:
if len(parameter) != 4:
return INVALID_PARAMETER, b""
ok = self._on_set_cumulative(struct.unpack("<I", parameter)[0] / 10)
return (SUCCESS if ok is not False else INVALID_PARAMETER), b""
if opcode == REQUEST_SUPPORTED_LOCATIONS and self._locations:
return SUCCESS, bytes(self._locations)
return OP_CODE_NOT_SUPPORTED, b""
[docs]
async def run(self):
"""Answer the SC Control Point, forever. Run it as a task."""
if self._control is None:
raise ValueError("this pod serves no control point")
await serve_control_point(self._control, self._handle, RESPONSE)