Document all known VSFRs (#47)

clean up VS (VString) class
- Radiacode apps refer to these by their hex values, not decimal.
- Add some other types I found in my logs.

Prefer hex notation rather than decimal, to align with radiacode
app debug output which also uses hex.

Replace magic numbers with their named versions

Author: ckuethe

radiacode/radiacode.py

@@ -6,16 +6,28 @@
 """
 
 import datetime
-import struct
 import platform
+import struct
 from typing import Optional
 
 from radiacode.bytes_buffer import BytesBuffer
 from radiacode.decoders.databuf import decode_VS_DATA_BUF
 from radiacode.decoders.spectrum import decode_RC_VS_SPECTRUM
 from radiacode.transports.bluetooth import Bluetooth
 from radiacode.transports.usb import Usb
-from radiacode.types import CTRL, VS, VSFR, DisplayDirection, DoseRateDB, Event, RareData, RawData, RealTimeData, Spectrum
+from radiacode.types import (
+    COMMAND,
+    CTRL,
+    VS,
+    VSFR,
+    DisplayDirection,
+    DoseRateDB,
+    Event,
+    RareData,
+    RawData,
+    RealTimeData,
+    Spectrum,
+)
 
 
 def spectrum_channel_to_energy(channel_number: int, a0: float, a1: float, a2: float) -> float:
@@ -76,7 +88,7 @@ def __init__(
             self._connection = Usb(serial_number=serial_number)
 
         # init
-        self.execute(b'\x07\x00', b'\x01\xff\x12\xff')
+        self.execute(COMMAND.SET_EXCHANGE, b'\x01\xff\x12\xff')
         self.set_local_time(datetime.datetime.now())
         self.device_time(0)
         self._base_time = datetime.datetime.now() + datetime.timedelta(seconds=128)
@@ -96,12 +108,11 @@ def __init__(
     def base_time(self) -> datetime.datetime:
         return self._base_time
 
-    def execute(self, reqtype: bytes, args: Optional[bytes] = None) -> BytesBuffer:
-        assert len(reqtype) == 2
+    def execute(self, reqtype: COMMAND, args: Optional[bytes] = None) -> BytesBuffer:
         req_seq_no = 0x80 + self._seq
         self._seq = (self._seq + 1) % 32
 
-        req_header = reqtype + b'\x00' + struct.pack('<B', req_seq_no)
+        req_header = struct.pack('<HBB', int(reqtype), 0, req_seq_no)
         request = req_header + (args or b'')
         full_request = struct.pack('<I', len(request)) + request
 
@@ -111,7 +122,7 @@ def execute(self, reqtype: bytes, args: Optional[bytes] = None) -> BytesBuffer:
         return response
 
     def read_request(self, command_id: int | VS | VSFR) -> BytesBuffer:
-        r = self.execute(b'\x26\x08', struct.pack('<I', int(command_id)))
+        r = self.execute(COMMAND.RD_VIRT_STRING, struct.pack('<I', int(command_id)))
         retcode, flen = r.unpack('<II')
         assert retcode == 1, f'{command_id}: got retcode {retcode}'
         # HACK: workaround for new firmware bug(?)
@@ -122,20 +133,20 @@ def read_request(self, command_id: int | VS | VSFR) -> BytesBuffer:
         return r
 
     def write_request(self, command_id: int | VSFR, data: Optional[bytes] = None) -> None:
-        r = self.execute(b'\x25\x08', struct.pack('<I', int(command_id)) + (data or b''))
+        r = self.execute(COMMAND.WR_VIRT_SFR, struct.pack('<I', int(command_id)) + (data or b''))
         retcode = r.unpack('<I')[0]
         assert retcode == 1
         assert r.size() == 0
 
     def batch_read_vsfrs(self, vsfr_ids: list[VSFR]) -> list[int]:
         assert len(vsfr_ids)
-        r = self.execute(b'\x2a\x08', b''.join(struct.pack('<I', int(c)) for c in vsfr_ids))
+        r = self.execute(COMMAND.RD_VIRT_SFR_BATCH, b''.join(struct.pack('<I', int(c)) for c in vsfr_ids))
         ret = [r.unpack('<I')[0] for _ in range(len(vsfr_ids))]
         assert r.size() == 0
         return ret
 
     def status(self) -> str:
-        r = self.execute(b'\x05\x00')
+        r = self.execute(COMMAND.GET_STATUS)
         flags = r.unpack('<I')
         assert r.size() == 0
         return f'status flags: {flags}'
@@ -149,10 +160,10 @@ def set_local_time(self, dt: datetime.datetime) -> None:
                 Microseconds are ignored.
         """
         d = struct.pack('<BBBBBBBB', dt.day, dt.month, dt.year - 2000, 0, dt.second, dt.minute, dt.hour, 0)
-        self.execute(b'\x04\x0a', d)
+        self.execute(COMMAND.SET_TIME, d)
 
     def fw_signature(self) -> str:
-        r = self.execute(b'\x01\x01')
+        r = self.execute(COMMAND.FW_SIGNATURE)
         signature = r.unpack('<I')[0]
         filename = r.unpack_string()
         idstring = r.unpack_string()
@@ -166,7 +177,7 @@ def fw_version(self) -> tuple[tuple[int, int, str], tuple[int, int, str]]:
                 - Boot version: (major, minor, date string)
                 - Target version: (major, minor, date string)
         """
-        r = self.execute(b'\x0a\x00')
+        r = self.execute(COMMAND.GET_VERSION)
         boot_minor, boot_major = r.unpack('<HH')
         boot_date = r.unpack_string()
         target_minor, target_major = r.unpack('<HH')
@@ -181,7 +192,7 @@ def hw_serial_number(self) -> str:
             str: Hardware serial number formatted as hyphen-separated hexadecimal groups
                 (e.g. "12345678-9ABCDEF0")
         """
-        r = self.execute(b'\x0b\x00')
+        r = self.execute(COMMAND.GET_SERIAL)
         serial_len = r.unpack('<I')[0]
         assert serial_len % 4 == 0
         serial_groups = [r.unpack('<I')[0] for _ in range(serial_len // 4)]
@@ -202,11 +213,11 @@ def serial_number(self) -> str:
         Returns:
             str: The device serial number as an ASCII string
         """
-        r = self.read_request(8)
+        r = self.read_request(VS.SERIAL_NUMBER)
         return r.data().decode('ascii')
 
     def commands(self) -> str:
-        br = self.read_request(257)
+        br = self.read_request(VS.SFR_FILE)
         return br.data().decode('ascii')
 
     # called with 0 after init!
@@ -254,7 +265,7 @@ def spectrum_reset(self) -> None:
         This clears the current spectrum data buffer, effectively resetting the spectrum
         measurement to start fresh.
         """
-        r = self.execute(b'\x27\x08', struct.pack('<II', int(VS.SPECTRUM), 0))
+        r = self.execute(COMMAND.WR_VIRT_STRING, struct.pack('<II', int(VS.SPECTRUM), 0))
         retcode = r.unpack('<I')[0]
         assert retcode == 1
         assert r.size() == 0
@@ -282,7 +293,7 @@ def set_energy_calib(self, coef: list[float]) -> None:
         """
         assert len(coef) == 3
         pc = struct.pack('<fff', *coef)
-        r = self.execute(b'\x27\x08', struct.pack('<II', int(VS.ENERGY_CALIB), len(pc)) + pc)
+        r = self.execute(COMMAND.WR_VIRT_STRING, struct.pack('<II', int(VS.ENERGY_CALIB), len(pc)) + pc)
         retcode = r.unpack('<I')[0]
         assert retcode == 1
 

radiacode/types.py

@@ -84,6 +84,8 @@ class RareData:
 
 
 class EventId(Enum):
+    POWER_OFF = 0
+    POWER_ON = 1
     TOGGLE_SIGNAL = 3
     DOSE_RESET = 4
     BATTERY_FULL = 7
@@ -92,6 +94,8 @@ class EventId(Enum):
     DOSE_RATE_ALARM2 = 10
     DOSE_ALARM1 = 12
     DOSE_ALARM2 = 13
+    TEXT_MESSAGE = 17
+    SPECTRUM_RESET = 19
     COUNT_RATE_ALARM1 = 20
     COUNT_RATE_ALARM2 = 21
 
@@ -145,62 +149,119 @@ def __int__(self) -> int:
 
 
 class VSFR(Enum):
-    DEVICE_CTRL = 1280
-    DEVICE_ON = 1283
-    DEVICE_LANG = 1282
-    DEVICE_TIME = 1284
-    DISP_CTRL = 1296
-    DISP_BRT = 1297
-    DISP_CONTR = 1298
-    DISP_OFF_TIME = 1299
-    DISP_ON = 1300
-    DISP_DIR = 1301
-    SOUND_CTRL = 1312
-    SOUND_VOL = 1313
-    SOUND_ON = 1314
-    SOUND_BUTTON = 1315
-    PLAY_SIGNAL = 1505
-    VIBRO_CTRL = 1328
-    VIBRO_ON = 1329
-    LEDS_CTRL = 1344
-    LED0_BRT = 1345
-    LED1_BRT = 1346
-    LED2_BRT = 1347
-    LED3_BRT = 1348
-    LEDS_ON = 1349
-    ALARM_MODE = 1504
-    MS_CTRL = 1536
-    MS_MODE = 1537
-    MS_SUB_MODE = 1538
-    MS_RUN = 1539
-    DOSE_RESET = 32775
-    # CR_LEV1_cp10s
-    # CR_LEV2_cp10s
-    # CR_UNITS
-    # DR_LEV1_uR_h
-    # DR_LEV2_uR_h
-    # DS_LEV1_uR
-    # DS_LEV2_uR
-    # DS_UNITS
-    # RAW_FILTER
-    # SYS_FW_VER_BT
+    DEVICE_CTRL = 0x0500
+    DEVICE_LANG = 0x0502
+    DEVICE_ON = 0x0503
+    DEVICE_TIME = 0x0504
+
+    DISP_CTRL = 0x0510
+    DISP_BRT = 0x0511
+    DISP_CONTR = 0x0512
+    DISP_OFF_TIME = 0x0513
+    DISP_ON = 0x0514
+    DISP_DIR = 0x0515
+    DISP_BACKLT_ON = 0x0516
+
+    SOUND_CTRL = 0x0520
+    SOUND_VOL = 0x0521
+    SOUND_ON = 0x0522
+    SOUND_BUTTON = 0x0523
+
+    VIBRO_CTRL = 0x0530
+    VIBRO_ON = 0x0531
+
+    LEDS_CTRL = 0x0540
+    LED0_BRT = 0x0541
+    LED1_BRT = 0x0542
+    LED2_BRT = 0x0543
+    LED3_BRT = 0x0544
+    LEDS_ON = 0x0545
+
+    ALARM_MODE = 0x05E0
+    PLAY_SIGNAL = 0x05E1
+
+    MS_CTRL = 0x0600
+    MS_MODE = 0x0601
+    MS_SUB_MODE = 0x0602
+    MS_RUN = 0x0603
+
+    BLE_TX_PWR = 0x0700
+
+    DR_LEV1_uR_h = 0x8000
+    DR_LEV2_uR_h = 0x8001
+    DS_LEV1_100uR = 0x8002
+    DS_LEV2_100uR = 0x8003
+    DS_UNITS = 0x8004
+    CPS_FILTER = 0x8005
+    RAW_FILTER = 0x8006
+    DOSE_RESET = 0x8007
+    CR_LEV1_cp10s = 0x8008
+    CR_LEV2_cp10s = 0x8009
+
+    USE_nSv_h = 0x800C
+
+    CHN_TO_keV_A0 = 0x8010
+    CHN_TO_keV_A1 = 0x8011
+    CHN_TO_keV_A2 = 0x8012
+    CR_UNITS = 0x8013
+    DS_LEV1_uR = 0x8014
+    DS_LEV2_uR = 0x8015
+
+    CPS = 0x8020
+    DR_uR_h = 0x8021
+    DS_uR = 0x8022
+
+    TEMP_degC = 0x8024
+    ACC_X = 0x8025
+    ACC_Y = 0x8026
+    ACC_Z = 0x8027
+    OPT = 0x8028
+
+    RAW_TEMP_degC = 0x8033
+    TEMP_UP_degC = 0x8034
+    TEMP_DN_degC = 0x8035
+
+    VBIAS_mV = 0xC000
+    COMP_LEV = 0xC001
+    CALIB_MODE = 0xC002
+    DPOT_RDAC = 0xC004
+    DPOT_RDAC_EEPROM = 0xC005
+    DPOT_TOLER = 0xC006
+
+    SYS_MCU_ID0 = 0xFFFF0000
+    SYS_MCU_ID1 = 0xFFFF0001
+    SYS_MCU_ID2 = 0xFFFF0002
+
+    SYS_DEVICE_ID = 0xFFFF0005
+    SYS_SIGNATURE = 0xFFFF0006
+    SYS_RX_SIZE = 0xFFFF0007
+    SYS_TX_SIZE = 0xFFFF0008
+    SYS_BOOT_VERSION = 0xFFFF0009
+    SYS_TARGET_VERSION = 0xFFFF000A
+    SYS_STATUS = 0xFFFF000B
+    SYS_MCU_VREF = 0xFFFF000C
+    SYS_MCU_TEMP = 0xFFFF000D
+    SYS_FW_VER_BT = 0xFFFF010
 
     def __int__(self) -> int:
         return self.value
 
 
 class VS(Enum):
     CONFIGURATION = 2
-    TEXT_MESSAGE = 15
-    DATA_BUF = 256
-    SPECTRUM = 512
-    ENERGY_CALIB = 514
-    SPEC_ACCUM = 517
-    SPEC_DIFF = 518  # TODO: what's that? Can be decoded by spectrum decoder
-    SPEC_RESET = 519  # TODO: looks like spectrum, but our spectrum decoder fails with `vlen == 7 unsupported`
-    MEM_SNAPSHOT = 224
-    # UNKNOWN_13 = 13
-    # UNKNOWN_240 = 240
+    FW_DESCRIPTOR = 3
+    SERIAL_NUMBER = 8
+    # UNKNOWN_13 = 0xd
+    TEXT_MESSAGE = 0xF
+    MEM_SNAPSHOT = 0xE0
+    # UNKNOWN_240 = 0xf0
+    DATA_BUF = 0x100
+    SFR_FILE = 0x101
+    SPECTRUM = 0x200
+    ENERGY_CALIB = 0x202
+    SPEC_ACCUM = 0x205
+    SPEC_DIFF = 0x206  # TODO: what's that? Can be decoded by spectrum decoder
+    SPEC_RESET = 0x207  # TODO: looks like spectrum, but our spectrum decoder fails with `vlen == 7 unsupported`
 
     def __int__(self) -> int:
         return self.value
@@ -218,3 +279,24 @@ class CTRL(Enum):
 
     def __int__(self) -> int:
         return self.value
+
+
+class COMMAND(Enum):
+    GET_STATUS = 0x0005
+    SET_EXCHANGE = 0x0007
+    GET_VERSION = 0x000A
+    GET_SERIAL = 0x000B
+    FW_IMAGE_GET_INFO = 0x0012
+    FW_SIGNATURE = 0x0101
+    RD_HW_CONFIG = 0x0807
+    RD_VIRT_SFR = 0x0824
+    WR_VIRT_SFR = 0x0825
+    RD_VIRT_STRING = 0x0826
+    WR_VIRT_STRING = 0x0827
+    RD_VIRT_SFR_BATCH = 0x082A
+    WR_VIRT_SFR_BATCH = 0x082B
+    RD_FLASH = 0x081C
+    SET_TIME = 0x0A04
+
+    def __int__(self) -> int:
+        return self.value