Refactor, Protocol Enhancements, and Device Ecosystem Reorganization

.github/workflows/build-docs.yml

@@ -0,0 +1,56 @@
+name: Build Documentation
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout pyharp repository
+        uses: actions/checkout@v4
+
+      - name: Clone harp.devices repository
+        uses: actions/checkout@v4
+        with:
+          repository: fchampalimaud/harp.devices
+          token: ${{ secrets.HARP_DEVICES_TOKEN }}
+          path: harp.devices
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install project dependencies
+        run: |
+          uv sync
+
+      - name: Build documentation
+        run: |
+          chmod +x ./run_docs.sh
+          ./run_docs.sh build
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+
+  deploy:
+    name: Deploy to Github pages
+    needs: build-docs
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+        pages: write # to deploy to Pages
+        id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+        name: github-pages
+        url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,6 +1,174 @@
-.idea/
-pyharp.egg-info/
-.python-version
-__pycache__
-tests/.pytest_cache
-**/*.bin
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v5.0.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: check-json
+        exclude: ^.devcontainer/devcontainer.json
+      - id: pretty-format-json
+        exclude: ^.devcontainer/devcontainer.json
+        args: [--autofix, --no-sort-keys]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.11.5"
+    hooks:
+      - id: ruff
+        args: [--exit-non-zero-on-fix]
+      - id: ruff-format

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "charliermarsh.ruff",
+    "meta.pyrefly"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.formatOnPaste": true,
+    "ruff.organizeImports": true,
+    "editor.codeActionsOnSave": {
+        "source.organizeImports": "explicit"
+    },
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python.pyrefly.displayTypeErrors": "force-on",
+}

10-harp.rules

@@ -0,0 +1,3 @@
+# UDEV rules for a Harp Device (actually an ftdi RS232 Serial [Uart] IC)
+SUBSYSTEMS=="usb", ENV{.LOCAL_ifNum}="$attr{bInterfaceNumber}"
+SUBSYSTEMS=="usb", KERNEL=="ttyUSB*", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666", SYMLINK+="harp_device_%E{.LOCAL_ifNum}"

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2020 OEPS & Filipe Carvalho
+Copyright (c) 2025 Hardware and Software Platform, Champalimaud Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,71 +1,12 @@
-
-
 # pyharp
 
-Harp implementation of the Harp protocol.
-
-## Edit the code
-
-Each Python user has is own very dear IDE for editing. Here, we are leaving instructions on how to edit this code using pyCharm, Anaconda and Poetry.
-
-The instructions are for beginner. Most of the users can just skip them.
-
-This was tested on a Windows machine, but should be similar to other systems.
-
-
-### 1. Install PyCHarm
-**PyCharm** can be download from [here](https://www.jetbrains.com/pycharm/download/). The Community version is enough.
-Download and install it.
-
-### 2. Install Anaconda
-
-**Anaconda** can be found [here](https://www.anaconda.com/products/individual).
-Download the version according to your computer and install it.
-- Unselect **Add Anaconda to the system PATH environment variable**
-- Select ** Register Anaconda as the system Pyhton**
-
-It's suggested to reboot your computer at this point
-
-### 3. Install Poetry
-
-Open the **Command Prompt** and execute the next command:
-```
-curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
-```
-
-### 4. Install pyharp
-
-Open **Anaconda**, navigate to the repository folder and execute the next commands:
-```
-poetry install
-poetry env info
-```
-
-The second comand will reply with a **Path:**.
-Select and copy this path.
-
-### 5. Using PyCharm to edit the code
+This project includes two main packages:
 
-1. Open **PyCharm** :)
-2. Go to File -> Open, select the repository folder, and click **OK**
-3. Go to File -> Settings -> Project:pyharp -> Project Interpreter
-3.1 Click in the gear in front of the Project Interpreter: and select **Add...**
-3.2 On Virtualenv Environment, chose Existing environment
-3.3 Select **python.exe** on the folder Scripts under  the path copied from the _poetry env info_ command
-3.4 Click **OK** and **OK**
+ - **harp-protocol**: Provides the core protocol definitions and utilities for the Harp protocol.
+   See [Protocol API Documentation](https://fchampalimaud.github.io/pyharp/api/protocol) for details.
 
-You are ready to go!
+ - **harp-serial**: Implements serial communication functionalities for generic Harp devices.
+   See [Serial API Documentation](https://fchampalimaud.github.io/pyharp/api/serial) for more information.
 
-### 6. Test the code
 
-Under **PyCharm**, Open one of the examples from the folder _examples_ (the _get_info.py_ is generic, so it's a good option) and update the COMx to your COM number.
-Right-click on top of the file and chose option _Run 'get_info.py_. You should read something like this in the console:
-```
-Device info:
-* Who am I: (2080) IblBehavior
-* HW version: 1.0
-* Assembly version: 0
-* HARP version: 1.6
-* Firmware version: 1.0
-* Device user name: IBL_rig_0
-```
+For specific Harp devices' packages please select the corresponding Harp device under the Devices section on the menu.

docs/api/protocol.md

@@ -0,0 +1,15 @@
+{% include-markdown "../../src/harp-protocol/README.md" %}
+
+---
+
+::: harp.protocol.MessageType
+::: harp.protocol.PayloadType
+::: harp.protocol.CommonRegisters
+::: harp.protocol.OperationMode
+::: harp.protocol.OperationCtrl
+::: harp.protocol.ResetMode
+::: harp.protocol.ClockConfig
+::: harp.protocol.messages.HarpMessage
+::: harp.protocol.messages.ReplyHarpMessage
+::: harp.protocol.messages.ReadHarpMessage
+::: harp.protocol.messages.WriteHarpMessage