Skip to content

DEV-1413: decode the Shimmer3R sound level channel (0x38) - #29

Open
marknolan wants to merge 2 commits into
mainfrom
DEV-1413_sound_level
Open

marknolan wants to merge 2 commits into
mainfrom
DEV-1413_sound_level

Conversation

@marknolan

@marknolan marknolan commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

What

The Shimmer3R firmware in ShimmerResearch/log-and-stream-common#230 and ShimmerResearch/shimmer3r-firmware#324 adds channel 0x38, SOUND_LEVEL. It carries the A-weighted level at the microphone as an int16, little-endian, in 0.01 dB(A), and -32768 means no level. The format is in log-and-stream-common's SHIMMER3_STREAMING_DATA_FORMAT.md §5.7. That firmware is merged, and LogAndStream_Shimmer3R v1.01.026 will be the first release with the channel. The doc comment names it. interpretDataPacketFormat already sized unknown IDs at two bytes, so packets stayed aligned, but the level was dropped.

  • SoundLevelSensor (new) decodes it. It always adds Sound Level Raw, and adds Calibrated in dB(A) while calibration is on: raw / 100, or NaN for -32768. SoundLevelSensor.calibrate(raw:) and NO_LEVEL are public.
  • In Shimmer3Protocol:
    • interpretDataPacketFormat enables it and sets its index when a Shimmer3R's inquiry lists 0x38. The channel has no enabled-sensors bit; the firmware turns it on from configuration byte 233 bit 4.
    • disableSensors turns it off, whatever the hardware.
    • buildMsg runs it before the battery.
  • Also added: Sensor.SensorUnits.decibelsA and ChannelContentsShimmer3.SoundLevel.
  • project.pbxproj: SoundLevelSensor.swift has all four entries.

Tested

  • CI was the first compile. It was written without Xcode. This PR's first CI run built it and ran the suite: ** TEST SUCCEEDED **, with the three new cases passing.

  • SensorTest adds three cases:

    • the calibration, including NaN for -32768;
    • the decode at its index, with calibration on and off;
    • four real packets a Shimmer3R streamed around its first level, from two captures (51 and 25 bytes, with the level at index 45 and 21).

    The firmware's own test rig decoded the same levels from the same bytes.

  • Not covered by a test: the wiring inside Shimmer3Protocol, because that class needs a live CBPeripheral (AGENTS.md). The packet indexes the test uses are the ones interpretDataPacketFormat computes for those channel lists, worked out by hand.

  • The full captures (122,482 stream packets and a 30,719-record SD file) decode exactly in the C# port (DEV-1413: decode the Shimmer3R sound level channel (0x38) Shimmer-C-API#232) and the web SDK (DEV-1413: Shimmer3R sound-level channel 0x38 and byte 233 bit 4 (0.5.13) shimmer-web-sdk#230). This API has no way to replay them without a radio.

Not done

  • Turning the channel on. That is configuration byte 233 bit 4, and this API doesn't write any Shimmer3R audio setting. Decoding needs neither: the channel is decoded whenever the firmware lists it.
  • No live unit.

Seen in passing, not changed

There are two problems with the battery, both older than this change, and they belong in their own fix:

  • BattVoltageSensor.processData always reads bytes 3-4, the first channel after the timestamp, not the battery's own packet index.
  • On a Shimmer3R the battery is never enabled. Neither initializeSensors nor interpretDataPacketFormat turns it on.

🤖 Generated with Claude Code

The Shimmer3R firmware adds channel 0x38, SOUND_LEVEL: the A-weighted level
at the microphone as an int16, little-endian, in 0.01 dB(A). -32768 means
no level. interpretDataPacketFormat already sized unknown IDs at two bytes,
so packets stayed aligned, but the level was dropped.

- SoundLevelSensor decodes it: RAW, and Calibrated in dB(A) (raw / 100,
  NaN for -32768) while calibration is on. SoundLevelSensor.calibrate()
  is public.
- Shimmer3Protocol enables it when a Shimmer3R's inquiry lists 0x38 (it
  has no enabled-sensors bit), turns it off in disableSensors whatever
  the hardware, and runs it in buildMsg before the battery.
- Sensor.SensorUnits.decibelsA, ChannelContentsShimmer3.SoundLevel.
- SoundLevelSensor.swift has its four project.pbxproj entries.

SensorTest covers the calibration, the decode at its index with and
without calibration, and four real packets from a Shimmer3R around its
first level. The wiring inside Shimmer3Protocol has no test: the class
needs a live CBPeripheral. Written without Xcode, so CI is the first
compile.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant