Skip to content

DEV-1413: Shimmer3R sound level channel (0x38), and keep configuration byte 233 on a full write - #346

Merged
JongChern merged 3 commits into
masterfrom
DEV-1413_sound_level
Nov 13, 2026
Merged

JongChern merged 3 commits into
masterfrom
DEV-1413_sound_level

Conversation

@marknolan

@marknolan marknolan commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

DEV-1413. Adds the Shimmer3R sound level channel to the driver. It also fixes an existing defect: a full configuration write zeroed configuration byte 233, which turned off the Shimmer3R's audio recording.

The channel (spec)

  • Channel ID 0x38, Shimmer3R only. 2 bytes, signed 16-bit little-endian.
  • Value: the A-weighted sound level (LAeq) over the microphone's most recent completed 128 ms block, in 0.01 dB(A) SPL. It is nominal: the firmware adds the microphone's datasheet sensitivity and nothing more, and no unit has been checked against a calibrated meter.
  • 0x8000 (-32768) means no level. That covers about the first 256 ms while capture settles, and capture that is stopped or has failed. CAL is NaN, never -327.68. UNCAL stays the raw count.
  • Lag: a value describes the block that ended 0-128 ms before the packet timestamp, plus main-loop latency (up to about 0.2 s more with a slow SD card). Nothing here corrects for it.
  • Position: the firmware puts it just before the ADS7028 block (GSR, ADCs, VBATT), so VBATT stays last. The decoder takes the position from the channel list like any other channel, so the same arm serves the inquiry response and Shimmer3R SD files (header channel list).
  • Enable: configuration byte 233 bit 4, not a sensor bitmap bit. Byte 4 bit 6 (0x4000) was deliberately not used: the SD path reads it as SDLogHeader.ECG_TO_HR_FW.
Byte 233 bits Meaning
0-1 Audio mode (0 off, 1 fingerprint, 2 fingerprint + raw, 3 raw)
2-3 Gain preset (0 default)
4 Sound level (new)
5-6 Cleared by firmware
7 Must be 0

Firmware that has the byte but not the channel clears bit 4, so support = write and read back.

Byte 233 fix

ShimmerObject.configBytesGenerate() builds the image it writes from zeros, so every full write from Consensys or Android put 0 in byte 233 and switched a Shimmer3R's audio mode off. Byte 233 is now modelled in ConfigByteLayoutShimmer3 (idxAudioConfig, Shimmer3R only) and owned by the new SensorSoundLevel:

  • On read, the sensor keeps bits 0-3 as read and takes its enable from bit 4.
  • On write, it puts back bits 0-3 and sets bit 4 from the sensor's state. Bits 5-7 are written as 0.
  • A byte with bit 7 set (erased flash, 0xFF) is treated as 0, as the firmware treats it.
  • A Shimmer3's byte 233 stays 0, as before: it has no microphone and never gets the sensor.

Changes

  • sensors/soundlevel/SensorSoundLevel (new, Shimmer3R only):
    • sensor ID SHIMMER_SOUND_LEVEL = 45, object-cluster name Sound_Level, unit CHANNEL_UNITS.DECIBELS_A (dB(A), new);
    • a "Sound Level" tile, appended to LABEL_SENSOR_TILE, so existing ordinals don't move;
    • the byte-233 config hooks.
  • ShimmerObject:
    • a Shimmer3R 0x38 arm in interpretDataPacketFormat() (i16);
    • the decode and calibration in buildMsg(), keyed on the channel being in the list rather than on a bitmap bit;
    • the sensor registered for Shimmer3R;
    • the bitmap-driven sensor map update skips the sound level sensor. It has no bitmap bit, so that update would always turn it off.

I kept this away from the lines #343 (DEV-971, byte 232) and #345 (DEV-1431) touch. A trial merge with each, and with #293, is clean.

Tests

No hardware.

  • API_00040_SoundLevelChannelTest (ShimmerDriver, 14 tests):
    • decoding: at the spec position and elsewhere in the list, the 0x8000 no-level value, signed values, an SD-type packet;
    • a Shimmer3 keeps the unknown-channel handling for 0x38;
    • byte 233: the audio mode goes back on a full write, all 256 values round-trip as the firmware keeps them, enabling changes only byte 233, the bitmap update doesn't turn it off, and a Shimmer3 writes 0.
  • API_00041_SoundLevelShimmerPCTest (ShimmerDriverPC, 2 tests): byte 233 survives deepClone(), the copy Consensys writes from, and decoding works with the arrays data structure.
  • Mutation checks: dropping the bits 0-3 preservation, or the bitmap-update skip, fails 4 of the new tests.
  • Results: ShimmerDriver 192/192 (178 + 14). ShimmerDriverPC 105/105 (103 + 2, run from a checkout named Shimmer-Java-Android-API).

Sibling APIs (same wire format)

Not covered

  • This driver has not decoded a packet or file from a unit with the channel. The firmware is merged (DEV-1413: Shimmer3R sound-level channel (SOUND_LEVEL, 0x38) log-and-stream-common#230, DEV-1413: Shimmer3R sound-level channel shimmer3r-firmware#324), and LogAndStream_Shimmer3R v1.01.026 will be the first release with it. Streams and an SD file captured from a unit on that firmware have been replayed through the web SDK, but not yet through this driver. The release needs the Java HIL as usual.
  • Firmware from before byte 233 existed (releases before v1.01.026, DEV-99) stores it untouched. There, bit 4 reads back set while no channel is sent. The channel list, not the bit, is what decoding goes by.
  • SD files: decoding from the header's channel list is covered. Setting the sensor's on/off state from the SD header (header byte 226 carries the corrected byte 233) belongs to the SD log parser outside this repo and is not done here.
  • The new "Sound Level" tile has not been looked at in Consensys.

🤖 Generated with Claude Code

…a full write

Decode the Shimmer3R sound level channel: ID 0x38, a signed 16-bit
little-endian count of 0.01 dB(A), LAeq over the microphone's most recent
128 ms block. 0x8000 means no level and calibrates to NaN. The decoder takes
the channel's position from the channel list (inquiry response or SD header),
like any other channel. A Shimmer3 never sends 0x38 and keeps the
unknown-channel handling.

The channel is enabled through configuration byte 233 bit 4, not a sensor
bitmap bit. A new SensorSoundLevel (Shimmer3R only) owns the byte: its
config hooks take the enable from bit 4 and give back bits 0-3 (the audio
mode and gain preset) as read. A full configuration write builds its image
from zeros, so until now it wrote 0 to byte 233 and also turned off a
Shimmer3R's audio recording. Bit 7 set (erased flash) reads as 0, as the
firmware reads it. A Shimmer3's byte 233 stays 0.

Tests: API_00040 (ShimmerDriver) covers decoding at the spec position and
elsewhere, the no-level value, SD, Shimmer3, and every value of byte 233.
API_00041 (ShimmerDriverPC) covers the byte surviving deepClone() and
decoding with the arrays data structure.

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

SensorSoundLevel's javadoc names LogAndStream_Shimmer3R v1.01.026, and the
firmware without byte 233 as the releases before it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@marknolan marknolan self-assigned this Nov 12, 2026
…1.026

Releases before v1.01.026 store configuration byte 233 untouched, so on
them bit 4 read back set while no channel was sent: the Sound Level tile
showed on, and nothing arrived. The bit also stayed in the unit, so a
later firmware update would turn the channel on unasked.

The sensor's compatibility list is now Shimmer3R LogAndStream v1.01.026
and later, so the tile is offered only there. On older firmware a bit 4
already set reads as off and the next configuration write clears it.
Bits 0-3, the audio mode the full write used to wipe, are kept on every
Shimmer3R firmware as before.

API_00040 runs at v1.01.026 and adds three tests at v1.01.025: the tile
is not offered, a stored bit 4 reads off and is cleared on write, and
enabling sets nothing. Without the gate all three fail. ShimmerDriver
195/195, ShimmerDriverPC 105/105, on JDK 11.

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

Copy link
Copy Markdown
Contributor

Pushed a09a0d4: the sound level is now offered only from LogAndStream_Shimmer3R v1.01.026.

Why: releases before v1.01.026 store byte 233 untouched, so there bit 4 read back set with no channel behind it. The tile showed on and nothing arrived, which fails DEV-1459's check ("hidden or reads back off" on firmware without the channel). The bit also stayed in the unit, so a later firmware update would switch the channel on unasked.

What changed:

  • listOfCompatibleVersionInfoSoundLevel is Shimmer3R LogAndStream v1.01.026 and later, so the tile is offered only there.
  • On older firmware, a bit 4 already set reads as off, and the next configuration write clears it. Bits 0-3 (the audio mode) are still kept on every Shimmer3R firmware.
  • API_00040 runs at v1.01.026 and adds three tests at v1.01.025. All three fail without the gate. ShimmerDriver 195/195, ShimmerDriverPC 105/105 on JDK 11.

One more point, not changed here: the firmware spec (INFOMEM §8.5) and the Rust host library read a byte with a reserved gain preset (bits 2-3 not 0) as 0: nothing recorded, sound level off. This PR treats only bit 7 as invalid, so for example 0x14 reads as sound level on. Firmware with the byte corrects it before it's read back, so the effect is small, but everyByteGoesBackAsTheFirmwareKeepsIt encodes the other rule.

@JongChern JongChern left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. The 0x38 decode and the byte 233 fix match the firmware spec, and with a09a0d4 the sound level is offered only from v1.01.026. The gain-preset rule from my comment can be a follow-up.

@JongChern
JongChern merged commit fb5d1f3 into master Nov 13, 2026
2 checks passed
JongChern added a commit that referenced this pull request Nov 16, 2026
…, audio status (#354)

The Java Shimmer Capture app gets the microphone half of shimmer-host-core's
CAPTURE.md "Event markers and audio recording", on the driver calls DEV-1459
brought to master (#353) and the sound level channel from DEV-1413 (#346).

- EventMarkersFrame, now "Event markers and audio": configuration byte 233's
  audio recording mode (Off, Fingerprint only, Fingerprint and raw audio, Raw
  audio only) and Sound Level, written with the whole configuration and read
  back, then an inquiry for the channel list; Read audio status from READY.
- Raw audio records speech: Write asks first where the new mode keeps raw
  audio and the unit's own does not, and writes nothing on No. The driver's
  raw audio switch is set for that one write and put back.
- MicrophoneSettings: byte 233's rules without Swing, so they are tested.
- Device tab: the status's Recording audio and Audio fault flags where the
  unit records audio, and whether the firmware has the event markers and
  audio recording.
- CaptureRulesTest: 11 tests, byte 233 as written checked on a ShimmerPC.
- README.

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.

2 participants