jeefs 0.1.3__tar.gz

jeefs-0.1.3/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: jeefs
+Version: 0.1.3
+Summary: JEEFS EEPROM header parser (JetHome EEPROM File System)
+Author-email: Viacheslav Bocharov <vb@jethome.com>
+License-Expression: GPL-2.0-or-later OR Apache-2.0
+Project-URL: Homepage, https://github.com/jethome-iot/jeefs
+Project-URL: Repository, https://github.com/jethome-iot/jeefs
+Project-URL: Documentation, https://github.com/jethome-iot/jeefs/tree/master/docs/python
+Project-URL: Issues, https://github.com/jethome-iot/jeefs/issues
+Keywords: eeprom,jethome,jeefs,embedded,header
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# JEEFS Header — Python Package
+
+Pure Python library for parsing and generating JEEFS EEPROM headers. The main API class `EEPROMHeaderV3` handles v3 headers; constants and field offsets for all versions (v1/v2/v3) are available via `jeefs.constants`. No native dependencies.
+
+## Installation
+
+```bash
+pip install jeefs
+```
+
+## Dependencies
+
+- Python >= 3.10
+- No external runtime dependencies (uses stdlib `struct`, `binascii`)
+
+## Building / Development
+
+```bash
+cd python
+uv venv .venv && uv pip install -e ".[test]"
+.venv/bin/python -m pytest tests/ -v
+```
+
+## API
+
+### `EEPROMHeaderV3` — main dataclass
+
+```python
+from jeefs.header import EEPROMHeaderV3
+```
+
+#### Creating a header
+
+```python
+header = EEPROMHeaderV3(
+    boardname="JetHub-D1p",
+    boardversion="2.0",
+    serial="SN-2024-001",
+    mac="F0:57:8D:01:02:03",
+)
+binary = header.to_bytes()  # 256-byte binary
+```
+
+#### Parsing from binary
+
+```python
+header = EEPROMHeaderV3.from_bytes(raw_data)
+print(header.boardname)   # "JetHub-D1p"
+print(header.mac)         # "F0:57:8D:01:02:03"
+print(header.serial)      # "SN-2024-001"
+```
+
+#### CRC verification
+
+```python
+# Instance method
+header = EEPROMHeaderV3.from_bytes(data)
+is_valid = header.verify_crc(data)
+
+# Static method (no instance needed)
+is_valid = EEPROMHeaderV3.verify_crc_static(data)
+```
+
+#### Validation
+
+```python
+errors = header.validate()
+if errors:
+    print("Invalid:", errors)
+```
+
+#### Partition image
+
+```python
+image = header.to_partition_image()  # 4096-byte flash image
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `boardname` | `str` | Board name (max 31 chars) |
+| `boardversion` | `str` | Board version (max 31 chars) |
+| `serial` | `str` | Serial number (max 31 chars) |
+| `usid` | `str` | CPU eFuse USID |
+| `cpuid` | `str` | CPU ID |
+| `mac` | `str` | MAC address ("AA:BB:CC:DD:EE:FF") |
+| `signature` | `bytes` | ECDSA signature (raw r\|\|s) |
+| `signature_algorithm` | `SignatureAlgorithm` | NONE / SECP192R1 / SECP256R1 |
+| `timestamp` | `int \| None` | Unix timestamp (auto-set if None/0) |
+
+### `SignatureAlgorithm` enum
+
+```python
+from jeefs.constants import SignatureAlgorithm
+
+SignatureAlgorithm.NONE       # 0
+SignatureAlgorithm.SECP192R1  # 1 (48-byte signature)
+SignatureAlgorithm.SECP256R1  # 2 (64-byte signature)
+```
+
+### Constants
+
+```python
+from jeefs.constants import (
+    EEPROM_MAGIC,          # b"JETHOME\x00"
+    EEPROM_HEADER_SIZE,    # 256
+    EEPROM_FIELDS,         # dict of {field: (offset, size)}
+    EEPROM_CRC_COVERAGE,   # 252
+    EEPROM_PARTITION_SIZE,  # 4096
+)
+```
+
+## Usage example
+
+See [examples/python/read_header.py](https://github.com/jethome-iot/jeefs/blob/master/examples/python/read_header.py) — reads an EEPROM binary, prints version, CRC status, board name, MAC address, and full v3 fields.
+
+## Testing
+
+```bash
+cd python
+python -m pytest tests/ -v   # 58 tests
+```
+
+## Format specification
+
+- [Header common properties](https://github.com/jethome-iot/jeefs/blob/master/docs/format/header-common.md)
+- [Header v3](https://github.com/jethome-iot/jeefs/blob/master/docs/format/header-v3.md)
+- [Full format spec](https://github.com/jethome-iot/jeefs/blob/master/EEPROM_FORMAT.md)

jeefs-0.1.3/README.md

@@ -0,0 +1,129 @@
+# JEEFS Header — Python Package
+
+Pure Python library for parsing and generating JEEFS EEPROM headers. The main API class `EEPROMHeaderV3` handles v3 headers; constants and field offsets for all versions (v1/v2/v3) are available via `jeefs.constants`. No native dependencies.
+
+## Installation
+
+```bash
+pip install jeefs
+```
+
+## Dependencies
+
+- Python >= 3.10
+- No external runtime dependencies (uses stdlib `struct`, `binascii`)
+
+## Building / Development
+
+```bash
+cd python
+uv venv .venv && uv pip install -e ".[test]"
+.venv/bin/python -m pytest tests/ -v
+```
+
+## API
+
+### `EEPROMHeaderV3` — main dataclass
+
+```python
+from jeefs.header import EEPROMHeaderV3
+```
+
+#### Creating a header
+
+```python
+header = EEPROMHeaderV3(
+    boardname="JetHub-D1p",
+    boardversion="2.0",
+    serial="SN-2024-001",
+    mac="F0:57:8D:01:02:03",
+)
+binary = header.to_bytes()  # 256-byte binary
+```
+
+#### Parsing from binary
+
+```python
+header = EEPROMHeaderV3.from_bytes(raw_data)
+print(header.boardname)   # "JetHub-D1p"
+print(header.mac)         # "F0:57:8D:01:02:03"
+print(header.serial)      # "SN-2024-001"
+```
+
+#### CRC verification
+
+```python
+# Instance method
+header = EEPROMHeaderV3.from_bytes(data)
+is_valid = header.verify_crc(data)
+
+# Static method (no instance needed)
+is_valid = EEPROMHeaderV3.verify_crc_static(data)
+```
+
+#### Validation
+
+```python
+errors = header.validate()
+if errors:
+    print("Invalid:", errors)
+```
+
+#### Partition image
+
+```python
+image = header.to_partition_image()  # 4096-byte flash image
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `boardname` | `str` | Board name (max 31 chars) |
+| `boardversion` | `str` | Board version (max 31 chars) |
+| `serial` | `str` | Serial number (max 31 chars) |
+| `usid` | `str` | CPU eFuse USID |
+| `cpuid` | `str` | CPU ID |
+| `mac` | `str` | MAC address ("AA:BB:CC:DD:EE:FF") |
+| `signature` | `bytes` | ECDSA signature (raw r\|\|s) |
+| `signature_algorithm` | `SignatureAlgorithm` | NONE / SECP192R1 / SECP256R1 |
+| `timestamp` | `int \| None` | Unix timestamp (auto-set if None/0) |
+
+### `SignatureAlgorithm` enum
+
+```python
+from jeefs.constants import SignatureAlgorithm
+
+SignatureAlgorithm.NONE       # 0
+SignatureAlgorithm.SECP192R1  # 1 (48-byte signature)
+SignatureAlgorithm.SECP256R1  # 2 (64-byte signature)
+```
+
+### Constants
+
+```python
+from jeefs.constants import (
+    EEPROM_MAGIC,          # b"JETHOME\x00"
+    EEPROM_HEADER_SIZE,    # 256
+    EEPROM_FIELDS,         # dict of {field: (offset, size)}
+    EEPROM_CRC_COVERAGE,   # 252
+    EEPROM_PARTITION_SIZE,  # 4096
+)
+```
+
+## Usage example
+
+See [examples/python/read_header.py](https://github.com/jethome-iot/jeefs/blob/master/examples/python/read_header.py) — reads an EEPROM binary, prints version, CRC status, board name, MAC address, and full v3 fields.
+
+## Testing
+
+```bash
+cd python
+python -m pytest tests/ -v   # 58 tests
+```
+
+## Format specification
+
+- [Header common properties](https://github.com/jethome-iot/jeefs/blob/master/docs/format/header-common.md)
+- [Header v3](https://github.com/jethome-iot/jeefs/blob/master/docs/format/header-v3.md)
+- [Full format spec](https://github.com/jethome-iot/jeefs/blob/master/EEPROM_FORMAT.md)

jeefs-0.1.3/jeefs/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: (GPL-2.0+ or Apache-2.0)
+"""EEPROM header generation, parsing, and validation.
+
+Provides a single source of truth for JEEPROMHeaderv3 binary format.
+"""
+
+from .constants import (
+    EEPROM_CRC_COVERAGE,
+    EEPROM_FIELDS,
+    EEPROM_HEADER_SIZE,
+    EEPROM_HEADER_VERSION,
+    EEPROM_MAGIC,
+    EEPROM_PARTITION_SIZE,
+    EEPROM_SIGNATURE_FIELD_SIZE,
+    SIGNATURE_SIZES,
+    SignatureAlgorithm,
+)
+from .header import EEPROMHeaderV3, parse_mac_string
+
+__all__ = [
+    "EEPROMHeaderV3",
+    "SignatureAlgorithm",
+    "SIGNATURE_SIZES",
+    "EEPROM_FIELDS",
+    "EEPROM_HEADER_SIZE",
+    "EEPROM_HEADER_VERSION",
+    "EEPROM_MAGIC",
+    "EEPROM_CRC_COVERAGE",
+    "EEPROM_SIGNATURE_FIELD_SIZE",
+    "EEPROM_PARTITION_SIZE",
+    "parse_mac_string",
+]

jeefs-0.1.3/jeefs/constants.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: (GPL-2.0+ or Apache-2.0)
+"""EEPROM header constants and signature algorithm definitions.
+
+Re-exports all constants from the auto-generated constants_generated module.
+The generated module is the single source of truth — produced by:
+    python -m jeefs_codegen --specs docs/format/*.md --py-output python/jeefs/constants_generated.py
+"""
+
+from .constants_generated import *  # noqa: F401,F403
+from .constants_generated import SignatureAlgorithm  # explicit for type checkers

jeefs-0.1.3/jeefs/constants_generated.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: (GPL-2.0+ or Apache-2.0)
+"""EEPROM format constants — auto-generated from docs/format/*.md.
+
+DO NOT EDIT — regenerate with:
+    python -m jeefs_codegen --specs docs/format/*.md --py-output python/jeefs/constants_generated.py
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class SignatureAlgorithm(IntEnum):
+    """JEEFSSignatureAlgorithm values.
+
+    Values:
+        NONE: No signature (0)
+        SECP192R1: ECDSA secp192r1/NIST P-192, r‖s (1)
+        SECP256R1: ECDSA secp256r1/NIST P-256, r‖s (2)
+    """
+
+    NONE = 0
+    SECP192R1 = 1
+    SECP256R1 = 2
+
+    @classmethod
+    def from_int(cls, value: int) -> "SignatureAlgorithm":
+        """Convert integer to enum, raising ValueError for unknown."""
+        try:
+            return cls(value)
+        except ValueError:
+            valid = ", ".join(f"{m.value}={m.name}" for m in cls)
+            raise ValueError(
+                f"Unknown value={value}. Valid values: {valid}"
+            ) from None
+
+SIGNATURE_SIZES: dict[SignatureAlgorithm, int] = {
+    SignatureAlgorithm.NONE: 0,
+    SignatureAlgorithm.SECP192R1: 48,
+    SignatureAlgorithm.SECP256R1: 64,
+}
+"""Signature byte size per algorithm (raw r||s format)."""
+
+# --- Named constants ---
+
+EEPROM_MAGIC = b"JETHOME\x00"
+EEPROM_MAGIC_LENGTH = 8
+EEPROM_HEADER_VERSION = 3
+EEPROM_SIGNATURE_FIELD_SIZE = 64
+EEPROM_FILE_NAME_LENGTH = 15
+EEPROM_MAC_LENGTH = 6
+EEPROM_SERIAL_LENGTH = 32
+EEPROM_USID_LENGTH = 32
+EEPROM_CPUID_LENGTH = 32
+EEPROM_BOARDNAME_LENGTH = 31
+EEPROM_BOARDVERSION_LENGTH = 31
+EEPROM_EMPTYBYTE = 0x00
+EEPROM_PARTITION_SIZE = 4096
+
+# Field offsets and sizes for JEEPROMHeaderv3
+EEPROM_FIELDS: dict[str, tuple[int, int]] = {
+    "magic": (0, 8),
+    "version": (8, 1),
+    "signature_version": (9, 1),
+    "header_reserved": (10, 2),
+    "boardname": (12, 32),
+    "boardversion": (44, 32),
+    "serial": (76, 32),
+    "usid": (108, 32),
+    "cpuid": (140, 32),
+    "mac": (172, 6),
+    "reserved2": (178, 2),
+    "signature": (180, 64),
+    "timestamp": (244, 8),
+    "crc32": (252, 4),
+}
+EEPROM_HEADER_SIZE = 256
+EEPROM_CRC_COVERAGE = 252
+
+# Field offsets and sizes for JEEPROMHeaderv2
+EEPROM_FIELDS_V2: dict[str, tuple[int, int]] = {
+    "magic": (0, 8),
+    "version": (8, 1),
+    "reserved1": (9, 3),
+    "boardname": (12, 32),
+    "boardversion": (44, 32),
+    "serial": (76, 32),
+    "usid": (108, 32),
+    "cpuid": (140, 32),
+    "mac": (172, 6),
+    "reserved2": (178, 2),
+    "reserved3": (180, 72),
+    "crc32": (252, 4),
+}
+EEPROM_V2_HEADER_SIZE = 256
+EEPROM_V2_CRC_COVERAGE = 252
+
+# Field offsets and sizes for JEEPROMHeaderv1
+EEPROM_FIELDS_V1: dict[str, tuple[int, int]] = {
+    "magic": (0, 8),
+    "version": (8, 1),
+    "reserved1": (9, 3),
+    "boardname": (12, 32),
+    "boardversion": (44, 32),
+    "serial": (76, 32),
+    "usid": (108, 32),
+    "cpuid": (140, 32),
+    "mac": (172, 6),
+    "reserved2": (178, 2),
+    "modules": (180, 32),
+    "reserved3": (212, 296),
+    "crc32": (508, 4),
+}
+EEPROM_V1_HEADER_SIZE = 512
+EEPROM_V1_CRC_COVERAGE = 508
+
+# Field offsets and sizes for JEEPROMHeaderversion
+EEPROM_FIELDS_JEEPROMHEADERVERSION: dict[str, tuple[int, int]] = {
+    "magic": (0, 8),
+    "version": (8, 1),
+    "reserved1": (9, 3),
+}
+
+# Field offsets and sizes for JEEFSFileHeaderv1
+EEPROM_FIELDS_JEEFSFILEHEADERV1: dict[str, tuple[int, int]] = {
+    "name": (0, 16),
+    "dataSize": (16, 2),
+    "crc32": (18, 4),
+    "nextFileAddress": (22, 2),
+}