Session summary: register map redesign context and decisions

[awickert]

Context

This issue captures design decisions and context agreed across several Claude Code sessions working in the Apis_Library repo, so the thread is not lost when moving to firmware work.

What is settled

The full 32-byte register map layout is agreed and documented. See Apis_Library repo conversation history for rationale. Summary:

Block 0 (0x00–0x07) — Identification & status

0x00  Status flags (bit 0 = ready; _waitUntilReady() must change from == 1 to & 0x01)
0x01  'A'  ─┐
0x02  'p'   │ ASCII device name, 4 bytes
0x03  'i'   │
0x04  's'  ─┘
0x05  HW version major
0x06  HW version minor
0x07  FW patch version

Block 1 (0x08–0x0F) — Range & config

0x08  Range low byte  ─┐ little-endian int16 [cm]
0x09  Range high byte ─┘
0x0A  Signal strength (uint8_t, from LiDAR Lite reg 0x0E)  ← prerequisite for #18
0x0B  Config (sensitivity [1:0]), writable  ← moves from current 0x01
0x0C  I2C address, writable (saved to EEPROM byte 6; takes effect on next boot)
0x0D–0x0F  Reserved

Block 2 (0x10–0x17) — Accelerometer raw

0x10–0x11  Accel X, little-endian int16
0x12–0x13  Accel Y, little-endian int16
0x14–0x15  Accel Z, little-endian int16
0x16–0x17  Reserved

Block 3 (0x18–0x1F) — Accelerometer offsets

0x18–0x19  Offset X, little-endian int16
0x1A–0x1B  Offset Y, little-endian int16
0x1C–0x1D  Offset Z, little-endian int16
0x1E–0x1F  Reserved

Key decisions

• No separate device type ID byte — 4-byte ASCII name alone gives ~1 in 4 billion collision probability.
• No NW manufacturer prefix — same reasoning.
• Version convention — major.minor = hardware revision; patch = firmware revision. Patch is not cosmetic: behavioral changes affecting library interaction require a bump.
• Library version check — begin() will read firmware version registers and warn (or return false) if incompatible. Exact minimum-version policy TBD in library.
• Status byte — bit 0 = ready flag; remaining bits reserved for LiDAR fail, accel fail, etc.
• Address selection — EEPROM-based only (no hardware address pins in current board revision). EEPROM layout: bytes 0–5 = accel offsets (existing), byte 6 = I2C address. Falls back to 0x50 if byte 6 is 0xFF.
• Config register moves from 0x01 → 0x0B — intentional breaking change, accepted.
• JP1 is the MIC2544 current-limit jumper, not an address jumper. No address-selection hardware exists.

Breaking changes relative to current firmware

• Config/sensitivity register: 0x01 → 0x0B
• Range registers: 0x02–0x03 → 0x08–0x09
• Accel raw: 0x04–0x09 → 0x10–0x15
• Accel offsets: 0x0A–0x0F → 0x18–0x1D

The library (Apis_Library#1) will be updated in lockstep. Both repos should get coordinated version bumps.

Related issues

• Apis_Library#1 — library update for new register map (to be done in parallel)
• Project-Apis#18 — expose signal strength at 0x0A
• Apis_Library#3 — adaptive sensitivity (depends on Expose LiDAR Lite signal strength in I2C register map #18)