Skip to content

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

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

marknolan wants to merge 2 commits into
masterfrom
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. Until now this API took 0x38 as an unknown two-byte channel, so packets stayed aligned but the level was dropped.

  • InterpretDataPacketFormat names it Sound Level (i16) on a Shimmer3R. Other hardware still treats 0x38 as an unknown two-byte channel.
  • BuildMsg adds RAW and CAL. CAL is raw / 100 in dB(A), or NaN for -32768, so every packet carries the same signals. The channel has no enabled-sensors bit, so BuildMsg finds it in the signal list. getSignalIndex() can't do that, because it returns 0 for a missing name.
  • Public helpers: CalibrateSoundLevel(), SOUND_LEVEL_NO_LEVEL, SignalUnits.DecibelsA, Shimmer3RConfiguration.SignalNames.SOUND_LEVEL and ChannelContentsShimmer3.SoundLevel.
  • ShimmerSDLog gets it with no change of its own, because a Shimmer3R file's header carries the channel list (count at 314, IDs from 315).

Tested

  • Unit tests: ShimmerBluetoothTests, built with MSBuild and run with VSTest as CI does: 130/130. That is 124 from master plus 6 new in ShimmerSoundLevelDecodeTest, which covers:
    • the scaling;
    • NaN;
    • the channel after the level;
    • three real packets from a Shimmer3R around its first level;
    • a Shimmer3;
    • a Shimmer3R SD log.
  • Replayed bench captures. I put two streams and an SD data file captured from a Shimmer3R on the channel's firmware build through this branch. The streams went through InterpretDataPacketFormat and BuildMsg, packet by packet, and the SD file through ShimmerSDLog. I compared each level, RAW and CAL, with the firmware test rig's decode of the same bytes (log-and-stream-common's HIL harness):
Capture Channels Count Mismatches First level
Stream, classic Bluetooth, 1024 Hz, every sensor 23, 0x38 21st 61,127 packets 0 packet 328
Stream, 512 Hz, IMU and the level 11, 0x38 10th 61,355 packets 0 packet 163
The SD data file a log during that stream wrote 11, 0x38 10th 30,719 records 0 record 0

Not done

  • Turning the channel on. That is configuration byte 233 bit 4, and this API doesn't write byte 233 or any Shimmer3R audio setting. Decoding needs neither: the channel is decoded whenever the firmware lists it.
  • SD header byte 226 (the stored byte 233) isn't read; the channel list decides.
  • ShimmerCaptureXamarin's copy of ShimmerBluetooth has no Shimmer3R support at all, so I left it alone.
  • No live unit. The firmware was benched on a unit; this code ran only against its recorded bytes.

Siblings

This is the C# port of DEV-1413's channel decode. The Swift port is ShimmerResearch/SwiftAPI#29. The pyshimmer change is on a fork branch; its upstream PR is not open yet.

🤖 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. Until now the API took it as an unnamed two-byte channel, so
packets stayed aligned but the level was dropped.

- InterpretDataPacketFormat names it "Sound Level" (i16) on a Shimmer3R.
  Other hardware still treats 0x38 as an unknown two-byte channel.
- BuildMsg adds RAW and CAL. CAL is raw / 100 in dB(A), or NaN for
  -32768, so every packet carries the same signals. The channel has no
  enabled-sensors bit, so BuildMsg finds it in the signal list instead.
- CalibrateSoundLevel() and SOUND_LEVEL_NO_LEVEL are public, and
  ChannelContentsShimmer3.SoundLevel names the ID.
- ShimmerSDLog gets it for free: a Shimmer3R file's header carries the
  channel list.

ShimmerSoundLevelDecodeTest covers the scaling, NaN, the channel after
it, three real packets from a Shimmer3R around its first level, a
Shimmer3, and an SD log.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

This branch has not been deployed

No deployments
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