Merge pull request #48 from LedgerHQ/add/apex

Trying to ease device management in Ledgered, to be used elsewhere

Author: Leereen

.github/workflows/build_and_tests.yml

@@ -45,9 +45,6 @@ jobs:
         pip install -U pip
         pip install -U .[dev]
 
-    - name: Run tests and generate coverage
-      run: pytest -v --tb=short tests/ --cov ledgered --cov-report xml
-
     - name: Run unit tests and generate coverage
       run: pytest -v --tb=short tests/unit --cov ledgered --cov-report xml
 

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2025-05-09
+
+### Added
+
+- Added `devices` module, declaring Ledger devices as class / enum, dynamically generated from a
+  JSON configuration file. This should enable to add new devices more easily, and device
+  characteristics are now reachable from a centralized place.
+
 ## [0.9.1] - 2025-03-26
 
 ### Fixed

MANIFEST.in

@@ -0,0 +1 @@
+include src/ledgered/devices.json

pyproject.toml

@@ -30,9 +30,10 @@ classifiers = [
 dynamic = [ "version" ]
 requires-python = ">=3.9"
 dependencies = [
-    "toml",
+    "pydantic",
     "pyelftools",
     "pygithub",
+    "toml",
 ]
 
 [project.optional-dependencies]

src/ledgered/devices/__init__.py

@@ -0,0 +1,71 @@
+import dataclasses
+import json
+from enum import IntEnum, auto
+from pathlib import Path
+from pydantic.dataclasses import dataclass
+
+
+class DeviceType(IntEnum):
+    NANOS = auto()
+    NANOSP = auto()
+    NANOX = auto()
+    STAX = auto()
+    FLEX = auto()
+
+
+@dataclass
+class Resolution:
+    x: int
+    y: int
+
+
+@dataclass
+class Device:
+    type: DeviceType
+    resolution: Resolution
+    touchable: bool = True
+    deprecated: bool = False
+    names: list[str] = dataclasses.field(default_factory=lambda: [])
+
+    @property
+    def name(self) -> str:
+        """
+        Returns the name of the current firmware's device
+        """
+        return self.type.name.lower()
+
+    @property
+    def is_nano(self):
+        """
+        States if the firmware's name starts with 'nano' or not.
+        """
+        return self.type in [DeviceType.NANOS, DeviceType.NANOSP, DeviceType.NANOX]
+
+    @classmethod
+    def from_dict(cls, dico: dict) -> "Device":
+        type = dico.pop("type")
+        dico["type"] = DeviceType[type.upper()]
+        return Device(**dico)
+
+
+class Devices:
+    _devices_file = Path(__file__).absolute().parent / "devices.json"
+    with _devices_file.open() as filee:
+        _devices = json.load(filee)
+
+    DEVICE_DATA = {item.type: item for item in [Device.from_dict(i) for i in _devices]}
+
+    def __iter__(self):
+        for d in self.DEVICE_DATA.values():
+            yield d
+
+    @classmethod
+    def get_by_type(cls, device_type: DeviceType) -> Device:
+        return cls.DEVICE_DATA[device_type]
+
+    @classmethod
+    def get_by_name(cls, name: str) -> Device:
+        for device in cls.DEVICE_DATA.values():
+            if name.lower() == device.name or name.lower() in device.names:
+                return device
+        raise KeyError(f"Device named '{name}' unknown")

src/ledgered/devices/devices.json

@@ -0,0 +1,7 @@
+[
+    {"type": "nanos", "resolution": {"x": 128, "y": 32}, "touchable": false, "deprecated": true},
+    {"type": "nanosp", "resolution": {"x": 128, "y": 64}, "touchable": false, "names": ["nanos+", "nanos2", "nanosplus"]},
+    {"type": "nanox", "resolution": {"x": 128, "y": 64}, "touchable": false},
+    {"type": "flex", "resolution": {"x": 480, "y": 600}},
+    {"type": "stax", "resolution": {"x": 400, "y": 670}}
+]

src/ledgered/manifest/__init__.py

@@ -1,6 +1,6 @@
 from .app import AppConfig
-from .constants import EXISTING_DEVICES, MANIFEST_FILE_NAME
+from .constants import MANIFEST_FILE_NAME
 from .manifest import Manifest
 from .tests import TestsConfig
 
-__all__ = ["AppConfig", "EXISTING_DEVICES", "Manifest", "MANIFEST_FILE_NAME", "TestsConfig"]
+__all__ = ["AppConfig", "Manifest", "MANIFEST_FILE_NAME", "TestsConfig"]

src/ledgered/manifest/app.py

@@ -3,7 +3,7 @@
 from typing import Iterable, Union
 
 from ledgered.serializers import Jsonable, JsonSet
-from .constants import EXISTING_DEVICES
+from ledgered.devices import Devices
 
 
 @dataclass
@@ -18,12 +18,7 @@ def __init__(self, sdk: str, build_directory: Union[str, Path], devices: Iterabl
             raise ValueError(f"'{sdk}' unknown. Must be either 'C' or 'Rust'")
         self.sdk = sdk
         self.build_directory = Path(build_directory)
-        devices = JsonSet(device.lower() for device in devices)
-        unknown_devices = devices.difference(EXISTING_DEVICES)
-        if unknown_devices:
-            unknown_devices_str = "', '".join(unknown_devices)
-            raise ValueError(f"Unknown devices: '{unknown_devices_str}'")
-        self.devices = devices
+        self.devices = JsonSet(Devices.get_by_name(device).name for device in devices)
 
     @property
     def is_rust(self) -> bool:

src/ledgered/manifest/constants.py

@@ -1,3 +1,2 @@
-EXISTING_DEVICES = ["nanos", "nanox", "nanos+", "stax", "flex"]
 MANIFEST_FILE_NAME = "ledger_app.toml"
 DEFAULT_USE_CASE = "default"

tests/unit/devices/__init__.py

@@ -0,0 +1,63 @@
+from ledgered.devices import Device, DeviceType, Devices, Resolution
+from unittest import TestCase
+
+
+class TestDevice(TestCase):
+    def setUp(self):
+        self.res = Resolution(x=10, y=20)
+
+    def test___init__simple(self):
+        type = DeviceType.NANOS
+        device = Device(type, self.res)
+        self.assertEqual(device.type, type)
+        self.assertEqual(device.touchable, True)
+        self.assertFalse(device.deprecated)
+        self.assertEqual(device.name, type.name.lower())
+        self.assertEqual(device.resolution, self.res)
+
+    def test_is_nano(self):
+        device = Device(DeviceType.NANOS, self.res)
+        self.assertTrue(device.is_nano)
+        device = Device(DeviceType.STAX, self.res)
+        self.assertFalse(device.is_nano)
+
+    def test_from_dict(self):
+        type, touchable, deprecated = "flex", False, True
+        device = Device.from_dict(
+            {
+                "type": type,
+                "resolution": {"x": self.res.x, "y": self.res.y},
+                "touchable": touchable,
+                "deprecated": deprecated,
+            }
+        )
+        self.assertEqual(device.type, DeviceType[type.upper()])
+        self.assertEqual(device.touchable, touchable)
+        self.assertEqual(device.deprecated, deprecated)
+        self.assertEqual(device.name, type)
+        self.assertEqual(device.resolution, Resolution(x=self.res.x, y=self.res.y))
+
+
+class TestDevices(TestCase):
+    def test_get_type_ok(self):
+        type = DeviceType.STAX
+        device = Devices.get_by_type(type)
+        self.assertIsInstance(device, Device)
+        self.assertEqual(device.type, type)
+
+    def test_get_type_nok(self):
+        with self.assertRaises(KeyError):
+            Devices.get_by_type(9)
+
+    def test_get_by_name_ok(self):
+        device = Devices.get_by_name("nanos+")
+        self.assertIsInstance(device, Device)
+        self.assertEqual(device.type, DeviceType.NANOSP)
+
+    def test_get_by_name_nok(self):
+        with self.assertRaises(KeyError):
+            Devices.get_by_name("non existent")
+
+    def test___iter__(self):
+        for d in Devices():
+            self.assertIsInstance(d, Device)

tests/unit/devices/test___init__.py

@@ -12,7 +12,7 @@ def test___init___ok_complete(self):
         config = AppConfig(sdk=sdk, build_directory=str(bd), devices=devices)
         self.assertEqual(config.sdk, sdk.lower())
         self.assertEqual(config.build_directory, bd)
-        self.assertEqual(config.devices, {device.lower() for device in devices})
+        self.assertEqual(config.devices, {"nanos", "nanosp"})
         self.assertTrue(config.is_rust)
         self.assertFalse(config.is_c)
 
@@ -21,8 +21,6 @@ def test___init___nok_unknown_sdk(self):
             AppConfig(sdk="Java", build_directory=str(), devices=set())
 
     def test___init___nok_unknown_device(self):
-        devices = {"hic sunt", "dracones"}
-        with self.assertRaises(ValueError) as error:
+        devices = {"nanosp", "flex", "hic sunt", "dracones"}
+        with self.assertRaises(KeyError):
             AppConfig(sdk="rust", build_directory=str(), devices=devices)
-        for device in devices:
-            self.assertIn(device, str(error.exception))