harp-python 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

harp/__init__.py

@@ -0,0 +1,5 @@
+from harp.io import REFERENCE_EPOCH, MessageType, read
+from harp.reader import create_reader
+from harp.schema import read_schema
+
+__all__ = ["REFERENCE_EPOCH", "MessageType", "read", "create_reader", "read_schema"]

harp/io.py

@@ -1,11 +1,28 @@
+from datetime import datetime
+from enum import IntEnum
 from os import PathLike
 from typing import Any, BinaryIO, Optional, Union
-from pandas._typing import Axes
+
 import numpy as np
 import pandas as pd
+from pandas._typing import Axes
+
+REFERENCE_EPOCH = datetime(1904, 1, 1)
+"""The reference epoch for UTC harp time."""
+
+
+class MessageType(IntEnum):
+    """Specifies the type of a Harp message."""
+
+    NA = 0
+    READ = 1
+    WRITE = 2
+    EVENT = 3
+
 
 _SECONDS_PER_TICK = 32e-6
-payloadtypes = {
+_messagetypes = [type.name for type in MessageType]
+_payloadtypes = {
     1: np.dtype(np.uint8),
     2: np.dtype(np.uint16),
     4: np.dtype(np.uint32),
@@ -20,39 +37,86 @@ payloadtypes = {
 
 def read(
     file: Union[str, bytes, PathLike[Any], BinaryIO],
+    address: Optional[int] = None,
+    dtype: Optional[np.dtype] = None,
+    length: Optional[int] = None,
     columns: Optional[Axes] = None,
+    epoch: Optional[datetime] = None,
+    keep_type: bool = False,
 ):
-    """
-    Read single-register Harp data from the specified file.
+    """Read single-register Harp data from the specified file.
+
+    Parameters
+    ----------
+    file
+        Open file object or filename containing binary data from
+        a single device register.
+    address
+        Expected register address. If specified, the address of
+        the first message in the file is used for validation.
+    dtype
+        Expected data type of the register payload. If specified, the
+        payload type of the first message in the file is used for validation.
+    length
+        Expected number of elements in register payload. If specified, the
+        payload length of the first message in the file is used for validation.
+    columns
+        The optional column labels to use for the data values.
+    epoch
+        Reference datetime at which time zero begins. If specified,
+        the result data frame will have a datetime index.
+    keep_type
+        Specifies whether to include a column with the message type.
 
-    :param str file or str or Path: Open file object or filename containing
-      binary data from a single device register.
-    :param str or array-like names: The optional column labels to use for
-      the data values.
-    :return: A pandas data frame containing harp event data, sorted by time.
+    Returns
+    -------
+        A pandas data frame containing message data, sorted by time.
     """
     data = np.fromfile(file, dtype=np.uint8)
     if len(data) == 0:
-        return pd.DataFrame(
-            columns=columns, index=pd.Index([], dtype=np.float64, name="time")
-        )
-
-    stride = data[1] + 2
-    length = len(data) // stride
-    payloadsize = stride - 12
-    payloadtype = payloadtypes[data[4] & ~0x10]
+        return pd.DataFrame(columns=columns, index=pd.Index([], dtype=np.float64, name="Time"))
+
+    if address is not None and address != data[2]:
+        raise ValueError(f"expected address {address} but got {data[2]}")
+
+    index = None
+    stride = int(data[1] + 2)
+    nrows = len(data) // stride
+    payloadtype = data[4]
+    payloadoffset = 5
+    if payloadtype & 0x10 != 0:
+        seconds = np.ndarray(nrows, dtype=np.uint32, buffer=data, offset=payloadoffset, strides=stride)
+        payloadoffset += 4
+        micros = np.ndarray(nrows, dtype=np.uint16, buffer=data, offset=payloadoffset, strides=stride)
+        payloadoffset += 2
+        time = micros * _SECONDS_PER_TICK + seconds
+        payloadtype = payloadtype & ~np.uint8(0x10)
+        if epoch is not None:
+            time = epoch + pd.to_timedelta(time, "s")  # type: ignore
+        index = pd.Series(time)
+        index.name = "Time"
+
+    payloadsize = stride - payloadoffset - 1
+    payloadtype = _payloadtypes[payloadtype]
+    if dtype is not None and dtype != payloadtype:
+        raise ValueError(f"expected payload type {dtype} but got {payloadtype}")
+
     elementsize = payloadtype.itemsize
-    payloadshape = (length, payloadsize // elementsize)
-    seconds = np.ndarray(length, dtype=np.uint32, buffer=data, offset=5, strides=stride)
-    micros = np.ndarray(length, dtype=np.uint16, buffer=data, offset=9, strides=stride)
-    seconds = micros * _SECONDS_PER_TICK + seconds
+    payloadshape = (nrows, payloadsize // elementsize)
+    if length is not None and length != payloadshape[1]:
+        raise ValueError(f"expected payload length {length} but got {payloadshape[1]}")
+
     payload = np.ndarray(
         payloadshape,
         dtype=payloadtype,
         buffer=data,
-        offset=11,
+        offset=payloadoffset,
         strides=(stride, elementsize),
     )
-    time = pd.Series(seconds)
-    time.name = "time"
-    return pd.DataFrame(payload, index=time, columns=columns)
+
+    result = pd.DataFrame(payload, index=index, columns=columns)
+    if keep_type:
+        msgtype = np.ndarray(nrows, dtype=np.uint8, buffer=data, offset=0, strides=stride)
+        msgtype = pd.Categorical.from_codes(msgtype, categories=_messagetypes)  # type: ignore
+        result[MessageType.__name__] = msgtype
+    return result

harp/model.py

@@ -5,36 +5,43 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
-
-from pydantic import BaseModel, ConfigDict, Field, RootModel, conint
-
-
-class Type(Enum):
-    U8 = 'U8'
-    S8 = 'S8'
-    U16 = 'U16'
-    S16 = 'S16'
-    U32 = 'U32'
-    S32 = 'S32'
-    U64 = 'U64'
-    S64 = 'S64'
-    Float = 'Float'
+from typing import Annotated, Dict, List, Optional, Union
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    RootModel,
+    field_serializer,
+)
+
+
+class PayloadType(str, Enum):
+    U8 = "uint8"
+    S8 = "int8"
+    U16 = "uint16"
+    S16 = "int16"
+    U32 = "uint32"
+    S32 = "int32"
+    U64 = "uint64"
+    S64 = "int64"
+    Float = "float32"
 
 
 class Access(Enum):
-    Read = 'Read'
-    Write = 'Write'
-    Event = 'Event'
+    Read = "Read"
+    Write = "Write"
+    Event = "Event"
 
 
 class MaskValueItem(BaseModel):
     model_config = ConfigDict(
-        extra='forbid',
+        extra="forbid",
     )
-    value: int = Field(..., description='Specifies the numerical mask value.')
+    value: int = Field(..., description="Specifies the numerical mask value.")
     description: Optional[str] = Field(
-        None, description='Specifies a summary description of the mask value function.'
+        None, description="Specifies a summary description of the mask value function."
     )
 
     def __int__(self):
@@ -47,14 +54,14 @@ class MaskValue(RootModel[Union[int, MaskValueItem]]):
 
 class BitMask(BaseModel):
     description: Optional[str] = Field(
-        None, description='Specifies a summary description of the bit mask function.'
+        None, description="Specifies a summary description of the bit mask function."
     )
     bits: Dict[str, MaskValue]
 
 
 class GroupMask(BaseModel):
     description: Optional[str] = Field(
-        None, description='Specifies a summary description of the group mask function.'
+        None, description="Specifies a summary description of the group mask function."
     )
     values: Dict[str, MaskValue]
 
@@ -62,55 +69,55 @@ class GroupMask(BaseModel):
 class MaskType(RootModel[str]):
     root: str = Field(
         ...,
-        description='Specifies the name of the bit mask or group mask used to represent the payload value.',
+        description="Specifies the name of the bit mask or group mask used to represent the payload value.",
     )
 
 
 class InterfaceType(RootModel[str]):
     root: str = Field(
         ...,
-        description='Specifies the name of the type used to represent the payload value in the high-level interface.',
+        description="Specifies the name of the type used to represent the payload value in the high-level interface.",
     )
 
 
 class Converter(Enum):
-    None_ = 'None'
-    Payload = 'Payload'
-    RawPayload = 'RawPayload'
+    None_ = "None"
+    Payload = "Payload"
+    RawPayload = "RawPayload"
 
 
 class MinValue(RootModel[float]):
     root: float = Field(
         ...,
-        description='Specifies the minimum allowable value for the payload or payload member.',
+        description="Specifies the minimum allowable value for the payload or payload member.",
     )
 
 
 class MaxValue(RootModel[float]):
     root: float = Field(
         ...,
-        description='Specifies the maximum allowable value for the payload or payload member.',
+        description="Specifies the maximum allowable value for the payload or payload member.",
     )
 
 
 class DefaultValue(RootModel[float]):
     root: float = Field(
         ...,
-        description='Specifies the default value for the payload or payload member.',
+        description="Specifies the default value for the payload or payload member.",
     )
 
 
 class PayloadMember(BaseModel):
     mask: Optional[int] = Field(
         None,
-        description='Specifies the mask used to read and write this payload member.',
+        description="Specifies the mask used to read and write this payload member.",
     )
     offset: Optional[int] = Field(
         None,
-        description='Specifies the payload array offset where this payload member is stored.',
+        description="Specifies the payload array offset where this payload member is stored.",
     )
     description: Optional[str] = Field(
-        None, description='Specifies a summary description of the payload member.'
+        None, description="Specifies a summary description of the payload member."
     )
     minValue: Optional[MinValue] = None
     maxValue: Optional[MaxValue] = None
@@ -121,23 +128,25 @@ class PayloadMember(BaseModel):
 
 
 class Visibility(Enum):
-    public = 'public'
-    private = 'private'
+    public = "public"
+    private = "private"
 
 
 class Register(BaseModel):
-    address: conint(le=255) = Field(
-        ..., description='Specifies the unique 8-bit address of the register.'
-    )
-    type: Type
-    length: Optional[conint(ge=1)] = Field(
-        None, description='Specifies the length of the register payload.'
-    )
+    address: Annotated[
+        int,
+        Field(le=255, description="Specifies the unique 8-bit address of the register."),
+    ]
+    type: Annotated[PayloadType, BeforeValidator(lambda v: PayloadType[v])]
+    length: Annotated[
+        Optional[int],
+        Field(ge=1, default=1, description="Specifies the length of the register payload."),
+    ]
     access: Union[Access, List[Access]] = Field(
-        ..., description='Specifies the expected use of the register.'
+        ..., description="Specifies the expected use of the register."
     )
     description: Optional[str] = Field(
-        None, description='Specifies a summary description of the register function.'
+        None, description="Specifies a summary description of the register function."
     )
     minValue: Optional[MinValue] = None
     maxValue: Optional[MaxValue] = None
@@ -145,40 +154,38 @@ class Register(BaseModel):
     maskType: Optional[MaskType] = None
     visibility: Optional[Visibility] = Field(
         None,
-        description='Specifies whether the register function is exposed in the high-level interface.',
+        description="Specifies whether the register function is exposed in the high-level interface.",
     )
     volatile: Optional[bool] = Field(
         None,
-        description='Specifies whether register values can be saved in non-volatile memory.',
+        description="Specifies whether register values can be saved in non-volatile memory.",
     )
     payloadSpec: Optional[Dict[str, PayloadMember]] = None
     interfaceType: Optional[InterfaceType] = None
     converter: Optional[Converter] = None
 
+    @field_serializer("type")
+    def _serialize_type(self, type: PayloadType):
+        return type.name
+
 
 class Registers(BaseModel):
     registers: Dict[str, Register] = Field(
         ...,
-        description='Specifies the collection of registers implementing the device function.',
+        description="Specifies the collection of registers implementing the device function.",
     )
     bitMasks: Optional[Dict[str, BitMask]] = Field(
         None,
-        description='Specifies the collection of masks available to be used with the different registers.',
+        description="Specifies the collection of masks available to be used with the different registers.",
     )
     groupMasks: Optional[Dict[str, GroupMask]] = Field(
         None,
-        description='Specifies the collection of group masks available to be used with the different registers.',
+        description="Specifies the collection of group masks available to be used with the different registers.",
     )
 
 
 class Model(Registers):
-    device: str = Field(..., description='Specifies the name of the device.')
-    whoAmI: int = Field(
-        ..., description='Specifies the unique identifier for this device type.'
-    )
-    firmwareVersion: str = Field(
-        ..., description='Specifies the semantic version of the device firmware.'
-    )
-    hardwareTargets: str = Field(
-        ..., description='Specifies the semantic version of the device hardware.'
-    )
+    device: str = Field(..., description="Specifies the name of the device.")
+    whoAmI: int = Field(..., description="Specifies the unique identifier for this device type.")
+    firmwareVersion: str = Field(..., description="Specifies the semantic version of the device firmware.")
+    hardwareTargets: str = Field(..., description="Specifies the semantic version of the device hardware.")

harp/reader.py

@@ -1,30 +1,72 @@
-import re
-from math import log2
+import os
+from collections import UserDict
+from dataclasses import dataclass
+from datetime import datetime
 from functools import partial
+from math import log2
+from os import PathLike
+from pathlib import Path
+from typing import Any, BinaryIO, Callable, Iterable, Mapping, Optional, Protocol, Union
+
+from numpy import dtype
 from pandas import DataFrame, Series
-from typing import Iterable, Callable, Union
-from harp.model import BitMask, GroupMask, MaskValueItem, Model, PayloadMember, Register
-from harp.io import read
+from pandas._typing import Axes
+
+from harp.io import MessageType, read
+from harp.model import BitMask, GroupMask, Model, PayloadMember, Register
+from harp.schema import read_schema
+
 
-_camel_to_snake_regex = re.compile(r"(?<!^)(?=[A-Z])")
+@dataclass
+class _ReaderParams:
+    path: Path
+    epoch: Optional[datetime] = None
+    keep_type: bool = False
+
+
+class _ReadRegister(Protocol):
+    def __call__(
+        self,
+        file: Optional[Union[str, bytes, PathLike[Any], BinaryIO]] = None,
+        epoch: Optional[datetime] = None,
+        keep_type: bool = False,
+    ) -> DataFrame: ...
 
 
 class RegisterReader:
     register: Register
-    read: Callable[[str], DataFrame]
+    read: _ReadRegister
 
-    def __init__(self, register: Register, read: Callable[[str], DataFrame]) -> None:
+    def __init__(
+        self,
+        register: Register,
+        read: _ReadRegister,
+    ) -> None:
         self.register = register
         self.read = read
 
 
+class RegisterMap(UserDict[str, RegisterReader]):
+    _address_map: Mapping[int, RegisterReader]
+
+    def __init__(self, registers: Mapping[str, RegisterReader]) -> None:
+        super().__init__(registers)
+        self._address_map = {value.register.address: value for value in registers.values()}
+
+    def __getitem__(self, key: Union[str, int]) -> RegisterReader:
+        if isinstance(key, int):
+            return self._address_map[key]
+        else:
+            return super().__getitem__(key)
+
+
 class DeviceReader:
     device: Model
-    registers: dict[str, RegisterReader]
+    registers: RegisterMap
 
-    def __init__(self, device: Model, registers: dict[str, RegisterReader]) -> None:
+    def __init__(self, device: Model, registers: Mapping[str, RegisterReader]) -> None:
         self.device = device
-        self.registers = registers
+        self.registers = RegisterMap(registers)
 
     def __dir__(self) -> Iterable[str]:
         return self.registers.keys()
@@ -33,12 +75,25 @@ class DeviceReader:
         return self.registers[__name]
 
 
-def _compose(f, g):
-    return lambda *a, **kw: f(g(*a, **kw))
-
+def _compose_parser(
+    f: Callable[[DataFrame], DataFrame],
+    g: Callable[..., DataFrame],
+    params: _ReaderParams,
+) -> Callable[..., DataFrame]:
+    def parser(
+        file: Optional[Union[str, bytes, PathLike[Any], BinaryIO]] = None,
+        columns: Optional[Axes] = None,
+        epoch: Optional[datetime] = params.epoch,
+        keep_type: bool = params.keep_type,
+    ):
+        df = g(file, columns, epoch, keep_type)
+        result = f(df)
+        type_col = df.get(MessageType.__name__)
+        if type_col is not None:
+            result[MessageType.__name__] = type_col
+        return result
 
-def _id_camel_to_snake(id: str):
-    return _camel_to_snake_regex.sub("_", id).lower()
+    return parser
 
 
 def _create_bit_parser(mask: int):
@@ -49,10 +104,7 @@ def _create_bit_parser(mask: int):
 
 
 def _create_bitmask_parser(bitMask: BitMask):
-    lookup = [
-        (_id_camel_to_snake(k), _create_bit_parser(int(v.root)))
-        for k, v in bitMask.bits.items()
-    ]
+    lookup = [(k, _create_bit_parser(int(v.root))) for k, v in bitMask.bits.items()]
 
     def parser(df: DataFrame):
         return DataFrame({n: f(df[0]) for n, f in lookup}, index=df.index)
@@ -83,14 +135,14 @@ def _create_payloadmember_parser(device: Model, member: PayloadMember):
     if offset is None:
         offset = 0
 
-    shift = None
+    shift = 0
     if member.mask is not None:
         shift = _mask_shift(member.mask)
 
     lookup = None
     if member.maskType is not None:
         key = member.maskType.root
-        groupMask = device.groupMasks.get(key)
+        groupMask = None if device.groupMasks is None else device.groupMasks.get(key)
         if groupMask is not None:
             lookup = _create_groupmask_lookup(groupMask)
 
@@ -103,7 +155,7 @@ def _create_payloadmember_parser(device: Model, member: PayloadMember):
         if member.mask is not None:
             series = series & member.mask
             if shift > 0:
-                series = Series(series.values >> shift, series.index)
+                series = Series(series.values >> shift, series.index)  # type: ignore
         if is_boolean:
             series = series != 0
         elif lookup is not None:
@@ -113,43 +165,107 @@ def _create_payloadmember_parser(device: Model, member: PayloadMember):
     return parser
 
 
-def _create_register_reader(device: Model, name: str):
+def _create_register_reader(register: Register, params: _ReaderParams):
+    def reader(
+        file: Optional[Union[str, bytes, PathLike[Any], BinaryIO]] = None,
+        columns: Optional[Axes] = None,
+        epoch: Optional[datetime] = params.epoch,
+        keep_type: bool = params.keep_type,
+    ):
+        if file is None:
+            file = f"{params.path}_{register.address}.bin"
+
+        data = read(
+            file,
+            address=register.address,
+            dtype=dtype(register.type),
+            length=register.length,
+            columns=columns,
+            epoch=epoch,
+            keep_type=keep_type,
+        )
+        return data
+
+    return reader
+
+
+def _create_register_parser(device: Model, name: str, params: _ReaderParams):
     register = device.registers[name]
-    reader = read
+    reader = _create_register_reader(register, params)
 
     if register.maskType is not None:
         key = register.maskType.root
-        bitMask = device.bitMasks.get(key)
+        bitMask = None if device.bitMasks is None else device.bitMasks.get(key)
         if bitMask is not None:
             parser = _create_bitmask_parser(bitMask)
-            reader = _compose(parser, reader)
+            reader = _compose_parser(parser, reader, params)
             return RegisterReader(register, reader)
 
-        groupMask = device.groupMasks.get(key)
+        groupMask = None if device.groupMasks is None else device.groupMasks.get(key)
         if groupMask is not None:
             parser = _create_groupmask_parser(name, groupMask)
-            reader = _compose(parser, reader)
+            reader = _compose_parser(parser, reader, params)
             return RegisterReader(register, reader)
 
     if register.payloadSpec is not None:
         payload_parsers = [
-            (_id_camel_to_snake(key), _create_payloadmember_parser(device, member))
+            (key, _create_payloadmember_parser(device, member))
             for key, member in register.payloadSpec.items()
         ]
 
         def parser(df: DataFrame):
             return DataFrame({n: f(df) for n, f in payload_parsers}, index=df.index)
 
-        reader = _compose(parser, reader)
+        reader = _compose_parser(parser, reader, params)
         return RegisterReader(register, reader)
 
-    columns = [_id_camel_to_snake(name)]
-    reader = partial(reader, columns=columns)
+    reader = partial(reader, columns=[name])
     return RegisterReader(register, reader)
 
 
-def create_reader(device: Model):
+def create_reader(
+    device: Union[str, PathLike, Model],
+    include_common_registers: bool = True,
+    epoch: Optional[datetime] = None,
+    keep_type: bool = False,
+):
+    """Creates a device reader object from the specified dataset or schema.
+
+    Parameters
+    ----------
+    device
+        A path to the device schema, dataset folder, or parsed device schema object
+        describing the device.
+    include_common_registers
+        Specifies whether to include the set of Harp common registers in the
+        parsed device schema object. If a parsed device schema object is provided,
+        this parameter is ignored.
+    epoch
+        The default reference datetime at which time zero begins. If specified,
+        the data frames returned by each register reader will have a datetime index.
+    keep_type
+        Specifies whether to include a column with the message type by default.
+
+    Returns
+    -------
+        A device reader object which can be used to read binary data for each
+        register or to access metadata about each register. Individual registers
+        can be accessed using dot notation using the name of the register as the
+        key.
+    """
+    if isinstance(device, Model):
+        base_path = Path(device.device)
+    else:
+        path = Path(device).absolute().resolve()
+        is_dir = os.path.isdir(path)
+        if is_dir:
+            device = path / "device.yml"
+
+        device = read_schema(device, include_common_registers)
+        base_path = path / device.device if is_dir else path.parent / device.device
+
     reg_readers = {
-        name: _create_register_reader(device, name) for name in device.registers.keys()
+        name: _create_register_parser(device, name, _ReaderParams(base_path, epoch, keep_type))
+        for name in device.registers.keys()
     }
     return DeviceReader(device, reg_readers)

harp/schema.py

@@ -1,31 +1,51 @@
+from importlib import resources
 from os import PathLike
-from pathlib import Path
 from typing import TextIO, Union
-from harp.model import Model, Registers
+
 from pydantic_yaml import parse_yaml_raw_as
 
-_common_yaml_path = Path(__file__).absolute().parent.joinpath("common.yml")
+from harp.model import Model, Registers
 
 
-def _read_common_registers(file: Union[str, PathLike, TextIO]) -> Registers:
-    try:
-        with open(file) as fileIO:
-            return _read_common_registers(fileIO)
-    except TypeError:
-        return parse_yaml_raw_as(Registers, file.read())
+def _read_common_registers() -> Registers:
+    file = resources.files(__package__) / "common.yml"
+    with file.open("r") as fileIO:
+        return parse_yaml_raw_as(Registers, fileIO.read())
+
+
+def read_schema(file: Union[str, PathLike, TextIO], include_common_registers: bool = True) -> Model:
+    """Read and parse a device schema from the specified file.
+
+    Parameters
+    ----------
+    file
+        Open file object or filename containing a YAML text stream describing
+        a device schema.
+    include_common_registers
+        Specifies whether to include the set of Harp common registers in the
+        returned device schema object.
 
+    Returns
+    -------
+        A Pydantic model object representing the Harp device schema.
+    """
 
-def read_schema(
-    file: Union[str, PathLike, TextIO], include_common_registers: bool = True
-) -> Model:
-    try:
+    if isinstance(file, (str, PathLike)):
         with open(file) as fileIO:
-            return read_schema(fileIO, include_common_registers)
-    except TypeError:
+            return read_schema(fileIO)
+    else:
         schema = parse_yaml_raw_as(Model, file.read())
-        if not "WhoAmI" in schema.registers and include_common_registers:
-            common = _read_common_registers(_common_yaml_path)
+        if "WhoAmI" not in schema.registers and include_common_registers:
+            common = _read_common_registers()
             schema.registers = dict(common.registers, **schema.registers)
-            schema.bitMasks = dict(common.bitMasks, **schema.bitMasks)
-            schema.groupMasks = dict(common.groupMasks, **schema.groupMasks)
+            if common.bitMasks:
+                schema.bitMasks = (
+                    common.bitMasks if schema.bitMasks is None else dict(common.bitMasks, **schema.bitMasks)
+                )
+            if common.groupMasks:
+                schema.groupMasks = (
+                    common.groupMasks
+                    if schema.groupMasks is None
+                    else dict(common.groupMasks, **schema.groupMasks)
+                )
         return schema

harp_python-0.3.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.1
+Name: harp-python
+Version: 0.3.0
+Summary: A low-level interface for loading binary Harp protocol data
+Author-email: Goncalo Lopes <g.lopes@neurogears.org>
+License: MIT License
+Project-URL: Bug Tracker, https://github.com/harp-tech/harp-python/issues
+Project-URL: Source Code, https://github.com/harp-tech/harp-python
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic-yaml
+Requires-Dist: pandas
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: codespell; extra == "dev"
+Provides-Extra: jupyter
+Requires-Dist: ipykernel; extra == "jupyter"
+Requires-Dist: matplotlib; extra == "jupyter"
+
+# harp-python
+
+A low-level interface to data collected with the [Harp binary protocol](https://harp-tech.org/protocol/BinaryProtocol-8bit.html).
+
+## How to install
+
+The source code is currently hosted on [GitHub](https://github.com/harp-tech/harp-python).
+
+Binary installers for the latest released version are available at the [Python Package Index (PyPI)](https://pypi.org/project/harp-python) and can be installed using `pip`.
+
+```sh
+pip install harp-python
+```
+
+The list of changes between each release can be found [here](https://github.com/harp-tech/harp-python/releases).
+
+## Data model 
+
+The interface makes use of a Pydantic data model generated from Harp device schema definitions. The schema data classes are used to automatically generate binary readers for each device.
+
+All binary data files from a single device need to be stored in the same folder alongside the device meta-schema, named `device.yml`. Each register file should have the following naming convention `<deviceName>_<registerAddress>.bin`.
+
+For example, for a dataset collected with a `Behavior` device, you might have:
+
+```
+📦device.harp
+ ┣ 📜Behavior_0.bin
+ ┣ 📜Behavior_1.bin
+...
+ ┗ 📜device.yml
+```
+
+## How to use
+
+### Create device reader object from schema
+
+```python
+import harp
+reader = harp.create_reader("device.harp")
+```
+
+### Read data from named register
+
+```python
+reader.OperationControl.read()
+```
+
+### Access register metadata
+
+```python
+reader.OperationControl.register.address
+```
+
+### Create device reader object with UTC datetime format
+
+```python
+reader = harp.create_reader("device.harp", epoch=harp.REFERENCE_EPOCH)
+```
+
+### Read data with message type information
+
+```python
+reader.OperationControl.read(keep_type=True)
+```
+
+### Read data from a specific file
+
+```python
+reader.OperationControl.read("data/Behavior_10.bin")
+```

harp_python-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+harp/__init__.py,sha256=P2PHGnd9Oz3LwrscBHKXqdYZimF7k57HcAaIaksRKc0,220
+harp/common.yml,sha256=qcejMFu00JjI5rkubuEDdrUu_uFkN17f_Ljb6yBd-RM,4452
+harp/io.py,sha256=an802KRCU-eSBXKWB7nXsomUBWcfAwEOZs9U188_MUM,4179
+harp/model.py,sha256=oJim5Gc42H4MJwpLwd2Y7KHsoeI_Yw3CO0o6qn7pJbQ,5805
+harp/reader.py,sha256=u-Taf6gmkQ5_PcsDRNskPBhZ7UsCcYL0WPlH0sEmjk0,8588
+harp/schema.py,sha256=bUr4WS-en03mzisIc9eAYiG7kReMmHdEvVwrhEpTboo,1816
+harp_python-0.3.0.dist-info/LICENSE,sha256=KxnuV3gNCp4WmLUC8DYWJvCKPdxMpwmWIzAYBYdqPrM,1104
+harp_python-0.3.0.dist-info/METADATA,sha256=lWiDbZSxbm8NmtXXopNpmmUN_h0wN0nIYc_LOrXr0s4,3190
+harp_python-0.3.0.dist-info/WHEEL,sha256=R06PA3UVYHThwHvxuRWMqaGcr-PuniXahwjmQRFMEkY,91
+harp_python-0.3.0.dist-info/top_level.txt,sha256=ztK1iHjgwmfXqxHCpu-e2uHIwdmodywYEUaWSODMvyM,5
+harp_python-0.3.0.dist-info/RECORD,,

{harp_python-0.1.0.dist-info → harp_python-0.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.3)
+Generator: setuptools (75.5.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

harp_python-0.1.0.dist-info/METADATA

@@ -1,69 +0,0 @@
-Metadata-Version: 2.1
-Name: harp-python
-Version: 0.1.0
-Summary: A low-level interface for loading binary Harp protocol data
-Author-email: Goncalo Lopes <g.lopes@neurogears.org>
-License: MIT License
-Project-URL: Bug Tracker, https://github.com/harp-tech/harp-python/issues
-Project-URL: Source Code, https://github.com/harp-tech/harp-python
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Operating System :: OS Independent
-Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.9.0
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pydantic-yaml
-Requires-Dist: pandas
-Provides-Extra: dev
-Requires-Dist: datamodel-code-generator ; extra == 'dev'
-Requires-Dist: black ; extra == 'dev'
-Provides-Extra: jupyter
-Requires-Dist: ipykernel ; extra == 'jupyter'
-Requires-Dist: matplotlib ; extra == 'jupyter'
-
-# harp-python
-
-A low-level interface to data collected with the [Harp](https://harp-tech.org/) binary protocol.
-
-## Data model 
-
-To regenerate Pydantic data models from device schema definitions, activate a virtual environment with `dev` dependencies, and run:
-
-```
-datamodel-codegen --input ./reflex-generator/schema/device.json --output harp/model.py --output-model-type pydantic_v2.BaseModel
-```
-
-> [!IMPORTANT]
-> Currently code generation adds an unwanted field at the very end of the data model definition `registers: Optional[Any] = None`. This declaration needs to be removed for serialization to work properly.
-
-## How to use
-
-### Read Harp device schema from YML file
-
-```python
-from harp.schema import read_schema
-schema = read_schema('device.yml')
-```
-
-### Create device reader object from schema
-
-```python
-from harp.reader import create_reader
-reader = create_reader(schema)
-```
-
-### Read data from named register
-
-```python
-reader.OperationControl.read("data/Behavior_10.bin")
-```
-
-### Access register metadata
-
-```python
-reader.OperationControl.register.address
-```

harp_python-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-harp/common.yml,sha256=qcejMFu00JjI5rkubuEDdrUu_uFkN17f_Ljb6yBd-RM,4452
-harp/io.py,sha256=qqdkoZe4Tqg6SEF8ZQmgN0iOGDbdBkgsXF6HaoUhfmQ,1907
-harp/model.py,sha256=20joms_-BLswhwPE4-AFpnGY8mh_qG6vvM8BdzOPhaU,5545
-harp/reader.py,sha256=8jAKcphayOWINvJF-uXcqC3QH7s4g_VjlKfNd_SrG2E,4515
-harp/schema.py,sha256=Xz5dA4dr13kr1vayB6debA5T2rNbFPfG7ssS3RPVFok,1202
-harp_python-0.1.0.dist-info/LICENSE,sha256=KxnuV3gNCp4WmLUC8DYWJvCKPdxMpwmWIzAYBYdqPrM,1104
-harp_python-0.1.0.dist-info/METADATA,sha256=K_U2ZcsXcxaInc_0JO7gXwQiKnaGpVuca-ct5HwIyj0,2193
-harp_python-0.1.0.dist-info/WHEEL,sha256=Xo9-1PvkuimrydujYJAjF7pCkriuXBpUPEjma1nZyJ0,92
-harp_python-0.1.0.dist-info/top_level.txt,sha256=ztK1iHjgwmfXqxHCpu-e2uHIwdmodywYEUaWSODMvyM,5
-harp_python-0.1.0.dist-info/RECORD,,