From 9fee831a9e53cfa0d2538d9cb5f58ee0128b36a1 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 9 May 2025 07:21:02 -0700 Subject: [PATCH 1/5] Initial reorganization of site content --- articles/collaborators.md | 2 ++ articles/distributors.md | 3 ++ articles/hardware-templates.md | 2 ++ articles/interface.md | 2 ++ articles/{about.md => motivation.md} | 12 ++----- articles/protocol.md | 2 ++ articles/toc.yml | 27 ++++++---------- articles/what-is-harp.md | 8 +++-- devices-page/harp-behavior.md | 1 + devices-page/toc.yml | 2 ++ docfx.json | 5 +++ index.md | 32 +++---------------- {articles => interface-page}/logging.md | 0 .../message-manipulation.md | 2 +- {articles => interface-page}/operators.md | 0 {articles => interface-page}/python.md | 0 interface-page/toc.yml | 7 ++++ protocol-page/toc.yml | 7 ++++ toc.yml | 12 +++++-- {articles => tutorials}/firmware.md | 0 tutorials/setup.md | 15 +++++++++ tutorials/toc.yml | 5 +++ 22 files changed, 85 insertions(+), 61 deletions(-) create mode 100644 articles/collaborators.md create mode 100644 articles/distributors.md create mode 100644 articles/hardware-templates.md create mode 100644 articles/interface.md rename articles/{about.md => motivation.md} (89%) create mode 100644 articles/protocol.md create mode 100644 devices-page/harp-behavior.md create mode 100644 devices-page/toc.yml rename {articles => interface-page}/logging.md (100%) rename {articles => interface-page}/message-manipulation.md (99%) rename {articles => interface-page}/operators.md (100%) rename {articles => interface-page}/python.md (100%) create mode 100644 interface-page/toc.yml create mode 100644 protocol-page/toc.yml rename {articles => tutorials}/firmware.md (100%) create mode 100644 tutorials/setup.md create mode 100644 tutorials/toc.yml diff --git a/articles/collaborators.md b/articles/collaborators.md new file mode 100644 index 00000000..69b45527 --- /dev/null +++ b/articles/collaborators.md @@ -0,0 +1,2 @@ +# Collaborators + diff --git a/articles/distributors.md b/articles/distributors.md new file mode 100644 index 00000000..28e78729 --- /dev/null +++ b/articles/distributors.md @@ -0,0 +1,3 @@ +# Distributors + +This is a placeholder for future vendors who are just involved in distributing Harp devices. \ No newline at end of file diff --git a/articles/hardware-templates.md b/articles/hardware-templates.md new file mode 100644 index 00000000..b92a33a8 --- /dev/null +++ b/articles/hardware-templates.md @@ -0,0 +1,2 @@ +# Devices + diff --git a/articles/interface.md b/articles/interface.md new file mode 100644 index 00000000..e68f836b --- /dev/null +++ b/articles/interface.md @@ -0,0 +1,2 @@ +# Interface + diff --git a/articles/about.md b/articles/motivation.md similarity index 89% rename from articles/about.md rename to articles/motivation.md index 5fbd82d9..e6c56011 100644 --- a/articles/about.md +++ b/articles/motivation.md @@ -1,15 +1,7 @@ ---- -uid: about ---- - -# What is Harp - -[!include[what-is-harp](./what-is-harp.md)] - -## Why Harp was developed +# Motivation Time is a critical variable in systems neuroscience experiments. As setups increase in complexity, temporally aligning multiple datastreams acquired from different devices rapidly becomes more difficult. Exploring how neural circuit activity relates to animal behaviour requires precise timestamping of experimental events, so that neural and behavioural data can be accurately ordered in time. Harp is being developed as a cross-institutional collaboration to develop an ecosystem of high-performance devices that make it easy for scientists to synchronize and extend the functionality of their setups. Harp devices should be able to configure, control, and track a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Connecting an extra Harp device to add functionality to a setup should be straightforward and place no extra burden on researchers. -From an engineering perspective, we also want to accelerate the development process of extending the functionality of a setup, and make it easier to develop new devices, deciding how these devices communicate a computer, and how researchers interact with the device. By agreeing beforehand how the entire ecosystem works together, from signal acquisition to analysis, we can support engineers not having to reinvent or attune protocols each time they wish to develop a new device. This leads to faster, cheaper, and more robust development of scientific tools. +From an engineering perspective, we also want to accelerate the development process of extending the functionality of a setup, and make it easier to develop new devices, deciding how these devices communicate a computer, and how researchers interact with the device. By agreeing beforehand how the entire ecosystem works together, from signal acquisition to analysis, we can support engineers not having to reinvent or attune protocols each time they wish to develop a new device. This leads to faster, cheaper, and more robust development of scientific tools. \ No newline at end of file diff --git a/articles/protocol.md b/articles/protocol.md new file mode 100644 index 00000000..76f1cf43 --- /dev/null +++ b/articles/protocol.md @@ -0,0 +1,2 @@ +# Protocol + diff --git a/articles/toc.yml b/articles/toc.yml index 96b8e561..bb498c37 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -1,19 +1,10 @@ -- name: Get started -- href: about.md +- name: Introduction - href: ../index.md -- name: Protocol -- name: Binary Protocol - href: ../protocol/BinaryProtocol-8bit.md -- name: Common Registers - href: ../protocol/Device.md -- name: Synchronization Clock - href: ../protocol/SynchronizationClock.md -- name: Control Interface -- href: operators.md -- href: firmware.md -- href: logging.md -- name: Message Manipulation - href: message-manipulation.md -- name: Data Interface -- name: Python - href: python.md +- href: motivation.md +- name: Ecosystem +- href: protocol.md +- href: interface.md +- href: hardware-templates.md +- name: Partners +- href: collaborators.md +- href: distributors.md \ No newline at end of file diff --git a/articles/what-is-harp.md b/articles/what-is-harp.md index a176caaf..79d17b49 100644 --- a/articles/what-is-harp.md +++ b/articles/what-is-harp.md @@ -1,9 +1,13 @@ -Harp is a standard for asynchronous real-time data acquisition and experimental control in neuroscience. It includes specifications for a lightweight and versatile binary communication protocol, a set of common registers for microcontroller firmware, and a clock synchronization protocol. +Harp is a standardized solution for automatic, sub-millisecond synchronization of data acquisition and experimental control in neuroscience. It includes: :::wrap-right ![Behavior Peripherals](~/images/behavior-peripherals.jpg) ::: + - [Protocols](./protocol.md) for communication between Harp devices and the host computer + - [Software interfaces](./interface.md) for interacting with devices and handling data + - [Hardware templates](./devices.md) for developing new Harp-compatible devices + Commands and events processed by all Harp devices are hardware timestamped and streamed back to the host computer over USB with a one millisecond latency. The stateless and symmetric communication protocol allows temporally accurate logging while avoiding the need for fixed sampling rates and redundant processing. Harp devices can be connected to a shared clock line and continuously self-synchronise their clocks to a precision of tens of microseconds. This means that all experimental events are timestamped on the same clock and no post-hoc alignment of timing is necessary. -The Harp ecosystem currently includes devices to configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices. \ No newline at end of file +The Harp ecosystem currently includes [devices](../devices-page/) to configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices. To learn how to use your Harp device, head on over to the [tutorials](../tutorials/tutorials.md). \ No newline at end of file diff --git a/devices-page/harp-behavior.md b/devices-page/harp-behavior.md new file mode 100644 index 00000000..61cf0058 --- /dev/null +++ b/devices-page/harp-behavior.md @@ -0,0 +1 @@ +# Harp Behaviour Board \ No newline at end of file diff --git a/devices-page/toc.yml b/devices-page/toc.yml new file mode 100644 index 00000000..4ec6d085 --- /dev/null +++ b/devices-page/toc.yml @@ -0,0 +1,2 @@ +- name: Core Devices +- href: harp-behavior.md \ No newline at end of file diff --git a/docfx.json b/docfx.json index 6081d15c..ebb2302e 100644 --- a/docfx.json +++ b/docfx.json @@ -34,6 +34,11 @@ "tutorials/**.md", "tutorials/**/toc.yml", "protocol/**.md", + "protocol-page/toc.yml", + "interface-page/**.md", + "interface-page/toc.yml", + "devices-page/**.md", + "devices-page/toc.yml", "toc.yml", "*.md" ], diff --git a/index.md b/index.md index 0dc3bdd4..386453cf 100644 --- a/index.md +++ b/index.md @@ -1,29 +1,7 @@ -Quick Start -=========== +--- +uid: about +--- -Harp is a standardized solution for: - - Automatic [sub-millisecond synchronization](./protocol/SynchronizationClock.md) across devices - - A [binary protocol](./protocol/BinaryProtocol-8bit.md) for communication between devices and PC - - [Hardware templates](./protocol/Device.md) for developing new devices +# What is Harp -All [Harp Devices](./protocol/whoami.md) implement the [Harp Protocol](./protocol/BinaryProtocol-8bit.md) to communicate with an host PC. The `Bonsai.Harp` library provides an implementation of the Harp protocol that can be used to interface with any Harp device. - -## How to install - -1. [Install Bonsai](https://bonsai-rx.org) -2. [Install FTDI D2XX Drivers](https://ftdichip.com/wp-content/uploads/2021/08/CDM212364_Setup.zip) -3. Install `Bonsai.Harp.Design` using the [Bonsai package manager](https://bonsai-rx.org/docs/articles/packages.html). - -## Device specific packages - -A high-level interface will usually be available for the specific Harp device you are using. To install them, first change the package manager **Package source** to `nuget.org`. Then, in the search bar, look for your device by typing: `harp.`. For instance, for the [Harp Behavior](xref:Harp.Behavior) board, you should find the following package: - -

Installing a Harp device package

- -The device nodes should now be available in the Bonsai Toolbox and you can start using them in your workflows. See [Operators](./articles/operators.md) for examples of how to manipulate and control Harp devices. - -## Next Steps - -- [Logging](./articles/logging.md) -- [Firmware](./articles/firmware.md) -- [Data Interface](./articles/python.md) \ No newline at end of file +[!include[what-is-harp](articles/what-is-harp.md)] \ No newline at end of file diff --git a/articles/logging.md b/interface-page/logging.md similarity index 100% rename from articles/logging.md rename to interface-page/logging.md diff --git a/articles/message-manipulation.md b/interface-page/message-manipulation.md similarity index 99% rename from articles/message-manipulation.md rename to interface-page/message-manipulation.md index 69f0725d..651b2d55 100644 --- a/articles/message-manipulation.md +++ b/interface-page/message-manipulation.md @@ -1,4 +1,4 @@ -# Manipulating Harp Messages +# Message Manipulation This section covers advanced message manipulation techniques that allow destructuring and constructing Harp messages at will from their essential elements. It is useful mostly for applications where routing of Harp messages is dynamic, when we need to build new commands based on previous responses, or when manipulating timestamped sequences for reactive computations that require keeping the original hardware timestamp of the result. diff --git a/articles/operators.md b/interface-page/operators.md similarity index 100% rename from articles/operators.md rename to interface-page/operators.md diff --git a/articles/python.md b/interface-page/python.md similarity index 100% rename from articles/python.md rename to interface-page/python.md diff --git a/interface-page/toc.yml b/interface-page/toc.yml new file mode 100644 index 00000000..97f8522c --- /dev/null +++ b/interface-page/toc.yml @@ -0,0 +1,7 @@ +- name: Control Interface +- href: operators.md +- href: logging.md +- href: message-manipulation.md +- name: Data Interface +- name: Python + href: python.md \ No newline at end of file diff --git a/protocol-page/toc.yml b/protocol-page/toc.yml new file mode 100644 index 00000000..23d9eb41 --- /dev/null +++ b/protocol-page/toc.yml @@ -0,0 +1,7 @@ +- name: Protocol +- name: Binary Protocol + href: ../protocol/BinaryProtocol-8bit.md +- name: Common Registers + href: ../protocol/Device.md +- name: Synchronization Clock + href: ../protocol/SynchronizationClock.md \ No newline at end of file diff --git a/toc.yml b/toc.yml index 8de88a1c..81e16999 100644 --- a/toc.yml +++ b/toc.yml @@ -1,6 +1,12 @@ -- name: Manual +- name: Overview href: articles/ -- name: Reference - href: api/ +- name: Protocol + href: protocol-page/ +- name: Interface + href: interface-page/ +- name: Devices + href: devices-page/ - name: Tutorials href: tutorials/ +- name: Reference + href: api/ \ No newline at end of file diff --git a/articles/firmware.md b/tutorials/firmware.md similarity index 100% rename from articles/firmware.md rename to tutorials/firmware.md diff --git a/tutorials/setup.md b/tutorials/setup.md new file mode 100644 index 00000000..cf6fad8f --- /dev/null +++ b/tutorials/setup.md @@ -0,0 +1,15 @@ +# Software Installation + +All [Harp Devices](../protocol/whoami.md) implement the [Harp Protocol](../protocol/BinaryProtocol-8bit.md) to communicate with an host PC. The `Bonsai.Harp` library provides an implementation of the Harp protocol that can be used to interface with any Harp device. To get started: + +1. [Install Bonsai](https://bonsai-rx.org) +2. [Install FTDI D2XX Drivers](https://ftdichip.com/wp-content/uploads/2021/08/CDM212364_Setup.zip) +3. Install `Bonsai.Harp.Design` using the [Bonsai package manager](https://bonsai-rx.org/docs/articles/packages.html). + +## Device specific packages + +A high-level interface will usually be available for the specific Harp device you are using. To install them, first change the package manager **Package source** to `nuget.org`. Then, in the search bar, look for your device by typing: `harp.`. For instance, for the [Harp Behavior](xref:Harp.Behavior) board, you should find the following package: + +

Installing a Harp device package

+ +The device nodes should now be available in the Bonsai Toolbox and you can start using them in your workflows. See [Operators](./articles/operators.md) for examples of how to manipulate and control Harp devices. \ No newline at end of file diff --git a/tutorials/toc.yml b/tutorials/toc.yml new file mode 100644 index 00000000..6f85c0cd --- /dev/null +++ b/tutorials/toc.yml @@ -0,0 +1,5 @@ +- name: Getting Started +- name: Software Installation + href: setup.md +- name: Firmware Update + href: firmware.md \ No newline at end of file From 5f0a6175b1452a119cf35b6af7b5354199aaf901 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Sat, 10 May 2025 15:17:15 -0700 Subject: [PATCH 2/5] Consolidate protocol and interface pages into new platform section --- articles/distributors.md | 2 +- articles/hardware-templates.md | 2 -- articles/hardware.md | 3 +++ articles/interface.md | 1 + articles/protocol.md | 1 + articles/toc.yml | 4 ++-- articles/what-is-harp.md | 10 +++++----- docfx.json | 7 +++---- interface-page/python.md | 5 ----- interface-page/toc.yml | 7 ------- platform/hardware-templates.md | 0 {interface-page => platform}/logging.md | 0 .../message-manipulation.md | 0 {interface-page => platform}/operators.md | 0 platform/python.md | 5 +++++ platform/toc.yml | 16 ++++++++++++++++ protocol-page/toc.yml | 7 ------- toc.yml | 6 ++---- tutorials/setup.md | 2 +- 19 files changed, 40 insertions(+), 38 deletions(-) delete mode 100644 articles/hardware-templates.md create mode 100644 articles/hardware.md delete mode 100644 interface-page/python.md delete mode 100644 interface-page/toc.yml create mode 100644 platform/hardware-templates.md rename {interface-page => platform}/logging.md (100%) rename {interface-page => platform}/message-manipulation.md (100%) rename {interface-page => platform}/operators.md (100%) create mode 100644 platform/python.md create mode 100644 platform/toc.yml delete mode 100644 protocol-page/toc.yml diff --git a/articles/distributors.md b/articles/distributors.md index 28e78729..eb500ca6 100644 --- a/articles/distributors.md +++ b/articles/distributors.md @@ -1,3 +1,3 @@ # Distributors -This is a placeholder for future vendors who are just involved in distributing Harp devices. \ No newline at end of file +Placeholder for future vendors who are just involved in distributing Harp devices. \ No newline at end of file diff --git a/articles/hardware-templates.md b/articles/hardware-templates.md deleted file mode 100644 index b92a33a8..00000000 --- a/articles/hardware-templates.md +++ /dev/null @@ -1,2 +0,0 @@ -# Devices - diff --git a/articles/hardware.md b/articles/hardware.md new file mode 100644 index 00000000..d6173adf --- /dev/null +++ b/articles/hardware.md @@ -0,0 +1,3 @@ +# Hardware + +Placeholder for overview of the hardware templates. \ No newline at end of file diff --git a/articles/interface.md b/articles/interface.md index e68f836b..df5e956f 100644 --- a/articles/interface.md +++ b/articles/interface.md @@ -1,2 +1,3 @@ # Interface +Placeholder for overview of the software interfaces. \ No newline at end of file diff --git a/articles/protocol.md b/articles/protocol.md index 76f1cf43..c1b962a7 100644 --- a/articles/protocol.md +++ b/articles/protocol.md @@ -1,2 +1,3 @@ # Protocol +Placeholder for overview of the various Harp protocols. \ No newline at end of file diff --git a/articles/toc.yml b/articles/toc.yml index bb498c37..2da31b10 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -1,10 +1,10 @@ - name: Introduction - href: ../index.md - href: motivation.md -- name: Ecosystem +- name: Platform - href: protocol.md - href: interface.md -- href: hardware-templates.md +- href: hardware.md - name: Partners - href: collaborators.md - href: distributors.md \ No newline at end of file diff --git a/articles/what-is-harp.md b/articles/what-is-harp.md index 79d17b49..2d5f1cdd 100644 --- a/articles/what-is-harp.md +++ b/articles/what-is-harp.md @@ -1,13 +1,13 @@ -Harp is a standardized solution for automatic, sub-millisecond synchronization of data acquisition and experimental control in neuroscience. It includes: +Harp is a standardized platform for automatic, sub-millisecond synchronization of data acquisition and experimental control in neuroscience. It includes: :::wrap-right ![Behavior Peripherals](~/images/behavior-peripherals.jpg) ::: - - [Protocols](./protocol.md) for communication between Harp devices and the host computer - - [Software interfaces](./interface.md) for interacting with devices and handling data - - [Hardware templates](./devices.md) for developing new Harp-compatible devices + - [Protocols](protocol.md) for communication between Harp devices and the host computer + - [Software interfaces](interface.md) for interacting with devices and handling data + - [Hardware templates](hardware.md) for developing new Harp-compatible devices Commands and events processed by all Harp devices are hardware timestamped and streamed back to the host computer over USB with a one millisecond latency. The stateless and symmetric communication protocol allows temporally accurate logging while avoiding the need for fixed sampling rates and redundant processing. Harp devices can be connected to a shared clock line and continuously self-synchronise their clocks to a precision of tens of microseconds. This means that all experimental events are timestamped on the same clock and no post-hoc alignment of timing is necessary. -The Harp ecosystem currently includes [devices](../devices-page/) to configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices. To learn how to use your Harp device, head on over to the [tutorials](../tutorials/tutorials.md). \ No newline at end of file +The Harp ecosystem currently includes [devices](../devices-page/harp-behaviour.md) to configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices. To learn how to use your Harp device, head on over to the [tutorials](../tutorials/setup.md). \ No newline at end of file diff --git a/docfx.json b/docfx.json index ebb2302e..92db7cb2 100644 --- a/docfx.json +++ b/docfx.json @@ -32,11 +32,10 @@ "articles/**.md", "articles/**/toc.yml", "tutorials/**.md", - "tutorials/**/toc.yml", + "tutorials/toc.yml", "protocol/**.md", - "protocol-page/toc.yml", - "interface-page/**.md", - "interface-page/toc.yml", + "platform/**.md", + "platform/toc.yml", "devices-page/**.md", "devices-page/toc.yml", "toc.yml", diff --git a/interface-page/python.md b/interface-page/python.md deleted file mode 100644 index 3b68b13d..00000000 --- a/interface-page/python.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -uid: python ---- - -[!include[harp-python](~/python/README.md)] diff --git a/interface-page/toc.yml b/interface-page/toc.yml deleted file mode 100644 index 97f8522c..00000000 --- a/interface-page/toc.yml +++ /dev/null @@ -1,7 +0,0 @@ -- name: Control Interface -- href: operators.md -- href: logging.md -- href: message-manipulation.md -- name: Data Interface -- name: Python - href: python.md \ No newline at end of file diff --git a/platform/hardware-templates.md b/platform/hardware-templates.md new file mode 100644 index 00000000..e69de29b diff --git a/interface-page/logging.md b/platform/logging.md similarity index 100% rename from interface-page/logging.md rename to platform/logging.md diff --git a/interface-page/message-manipulation.md b/platform/message-manipulation.md similarity index 100% rename from interface-page/message-manipulation.md rename to platform/message-manipulation.md diff --git a/interface-page/operators.md b/platform/operators.md similarity index 100% rename from interface-page/operators.md rename to platform/operators.md diff --git a/platform/python.md b/platform/python.md new file mode 100644 index 00000000..999b0b49 --- /dev/null +++ b/platform/python.md @@ -0,0 +1,5 @@ +--- +uid: python +--- + +[!include[harp-python](../python/README.md)] \ No newline at end of file diff --git a/platform/toc.yml b/platform/toc.yml new file mode 100644 index 00000000..a72a77bb --- /dev/null +++ b/platform/toc.yml @@ -0,0 +1,16 @@ +- name: Protocol +- name: Binary Protocol + href: ../protocol/BinaryProtocol-8bit.md +- name: Common Registers + href: ../protocol/Device.md +- name: Synchronization Clock + href: ../protocol/SynchronizationClock.md +- name: Control Interface +- href: operators.md +- href: logging.md +- href: message-manipulation.md +- name: Data Interface +- name: Python + href: python.md +- name: Hardware templates + href: hardware-templates.md \ No newline at end of file diff --git a/protocol-page/toc.yml b/protocol-page/toc.yml deleted file mode 100644 index 23d9eb41..00000000 --- a/protocol-page/toc.yml +++ /dev/null @@ -1,7 +0,0 @@ -- name: Protocol -- name: Binary Protocol - href: ../protocol/BinaryProtocol-8bit.md -- name: Common Registers - href: ../protocol/Device.md -- name: Synchronization Clock - href: ../protocol/SynchronizationClock.md \ No newline at end of file diff --git a/toc.yml b/toc.yml index 81e16999..441c2683 100644 --- a/toc.yml +++ b/toc.yml @@ -1,9 +1,7 @@ - name: Overview href: articles/ -- name: Protocol - href: protocol-page/ -- name: Interface - href: interface-page/ +- name: Platform + href: platform/ - name: Devices href: devices-page/ - name: Tutorials diff --git a/tutorials/setup.md b/tutorials/setup.md index cf6fad8f..f1f4f947 100644 --- a/tutorials/setup.md +++ b/tutorials/setup.md @@ -12,4 +12,4 @@ A high-level interface will usually be available for the specific Harp device yo

Installing a Harp device package

-The device nodes should now be available in the Bonsai Toolbox and you can start using them in your workflows. See [Operators](./articles/operators.md) for examples of how to manipulate and control Harp devices. \ No newline at end of file +The device nodes should now be available in the Bonsai Toolbox and you can start using them in your workflows. See [Operators](../platform/operators.md) for examples of how to manipulate and control Harp devices. \ No newline at end of file From b4997a6276c5ba2273a21a7eaeeb481ffaae2736 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Sun, 11 May 2025 11:21:57 -0700 Subject: [PATCH 3/5] Add tutorial and device page placeholders --- articles/collaborators.md | 1 + articles/distributors.md | 2 +- articles/hardware.md | 3 --- articles/toc.yml | 4 ---- articles/what-is-harp.md | 8 ++++---- devices-page/harp-behavior.md | 2 +- devices-page/harp-soundcard.md | 1 + devices-page/harp-timestamp-generator-gen3.md | 1 + devices-page/toc.yml | 10 ++++++++-- platform/hardware-cores.md | 3 +++ platform/hardware-templates.md | 3 +++ {articles => platform}/interface.md | 0 {articles => platform}/protocol.md | 0 platform/toc.yml | 11 +++++++++-- tutorials/harp-behavior-dataacquisition.md | 9 +++++++++ tutorials/harp-behavior-peripheralcontrol.md | 11 +++++++++++ tutorials/toc.yml | 5 ++++- 17 files changed, 56 insertions(+), 18 deletions(-) delete mode 100644 articles/hardware.md create mode 100644 devices-page/harp-soundcard.md create mode 100644 devices-page/harp-timestamp-generator-gen3.md create mode 100644 platform/hardware-cores.md rename {articles => platform}/interface.md (100%) rename {articles => platform}/protocol.md (100%) create mode 100644 tutorials/harp-behavior-dataacquisition.md create mode 100644 tutorials/harp-behavior-peripheralcontrol.md diff --git a/articles/collaborators.md b/articles/collaborators.md index 69b45527..f07a5fe2 100644 --- a/articles/collaborators.md +++ b/articles/collaborators.md @@ -1,2 +1,3 @@ # Collaborators +Placeholder for links to collaborators and acknowledgement of contributions. \ No newline at end of file diff --git a/articles/distributors.md b/articles/distributors.md index eb500ca6..32b41451 100644 --- a/articles/distributors.md +++ b/articles/distributors.md @@ -1,3 +1,3 @@ # Distributors -Placeholder for future vendors who are just involved in distributing Harp devices. \ No newline at end of file +Placeholder for links to vendors who are distributing Harp devices. \ No newline at end of file diff --git a/articles/hardware.md b/articles/hardware.md deleted file mode 100644 index d6173adf..00000000 --- a/articles/hardware.md +++ /dev/null @@ -1,3 +0,0 @@ -# Hardware - -Placeholder for overview of the hardware templates. \ No newline at end of file diff --git a/articles/toc.yml b/articles/toc.yml index 2da31b10..3d8022fb 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -1,10 +1,6 @@ - name: Introduction - href: ../index.md - href: motivation.md -- name: Platform -- href: protocol.md -- href: interface.md -- href: hardware.md - name: Partners - href: collaborators.md - href: distributors.md \ No newline at end of file diff --git a/articles/what-is-harp.md b/articles/what-is-harp.md index 2d5f1cdd..ef03256c 100644 --- a/articles/what-is-harp.md +++ b/articles/what-is-harp.md @@ -4,10 +4,10 @@ Harp is a standardized platform for automatic, sub-millisecond synchronization o ![Behavior Peripherals](~/images/behavior-peripherals.jpg) ::: - - [Protocols](protocol.md) for communication between Harp devices and the host computer - - [Software interfaces](interface.md) for interacting with devices and handling data - - [Hardware templates](hardware.md) for developing new Harp-compatible devices + - [Protocols](~/platform/protocol.md) for communication between Harp devices and the host computer + - [Software interfaces](~/platform/interface.md) for interacting with devices and handling data + - [Hardware templates](~/platform/hardware-templates.md) for developing new Harp-compatible devices Commands and events processed by all Harp devices are hardware timestamped and streamed back to the host computer over USB with a one millisecond latency. The stateless and symmetric communication protocol allows temporally accurate logging while avoiding the need for fixed sampling rates and redundant processing. Harp devices can be connected to a shared clock line and continuously self-synchronise their clocks to a precision of tens of microseconds. This means that all experimental events are timestamped on the same clock and no post-hoc alignment of timing is necessary. -The Harp ecosystem currently includes [devices](../devices-page/harp-behaviour.md) to configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices. To learn how to use your Harp device, head on over to the [tutorials](../tutorials/setup.md). \ No newline at end of file +The Harp ecosystem currently includes [devices](~/devices-page/harp-behavior.md) to configure, control, and collect data from a wide range of peripheral devices such as cameras, LEDs, nosepokes, and motors. Combining Harp devices is an easy way to extend experimental setup functionality with integrated timestamp synchronisation across devices. To learn how to use your Harp device, head on over to the [tutorials](~/tutorials/setup.md). \ No newline at end of file diff --git a/devices-page/harp-behavior.md b/devices-page/harp-behavior.md index 61cf0058..94c67b9d 100644 --- a/devices-page/harp-behavior.md +++ b/devices-page/harp-behavior.md @@ -1 +1 @@ -# Harp Behaviour Board \ No newline at end of file +[!include[Harp Behavior Board](~/src/device.behavior/README.md)] \ No newline at end of file diff --git a/devices-page/harp-soundcard.md b/devices-page/harp-soundcard.md new file mode 100644 index 00000000..bd888b5b --- /dev/null +++ b/devices-page/harp-soundcard.md @@ -0,0 +1 @@ +[!include[Harp Sound Card](~/src/device.soundcard/README.md)] \ No newline at end of file diff --git a/devices-page/harp-timestamp-generator-gen3.md b/devices-page/harp-timestamp-generator-gen3.md new file mode 100644 index 00000000..fcd0be1c --- /dev/null +++ b/devices-page/harp-timestamp-generator-gen3.md @@ -0,0 +1 @@ +[!include[Harp Timestamp Generator Gen3](~/src/device.timestampgeneratorgen3/README.md)] \ No newline at end of file diff --git a/devices-page/toc.yml b/devices-page/toc.yml index 4ec6d085..c9a5f8ba 100644 --- a/devices-page/toc.yml +++ b/devices-page/toc.yml @@ -1,2 +1,8 @@ -- name: Core Devices -- href: harp-behavior.md \ No newline at end of file +- name: Multi-purpose Devices +- name: Harp Behavior Board + href: harp-behavior.md +- name: Harp Timestamp Generator Gen3 + href: harp-timestamp-generator-gen3.md +- name: Single-purpose Devices +- name: Harp Sound Card + href: harp-soundcard.md \ No newline at end of file diff --git a/platform/hardware-cores.md b/platform/hardware-cores.md new file mode 100644 index 00000000..66c2ae30 --- /dev/null +++ b/platform/hardware-cores.md @@ -0,0 +1,3 @@ +# Hardware + +Placeholder for article on the hardware cores (ATxmega, Pico) \ No newline at end of file diff --git a/platform/hardware-templates.md b/platform/hardware-templates.md index e69de29b..d6173adf 100644 --- a/platform/hardware-templates.md +++ b/platform/hardware-templates.md @@ -0,0 +1,3 @@ +# Hardware + +Placeholder for overview of the hardware templates. \ No newline at end of file diff --git a/articles/interface.md b/platform/interface.md similarity index 100% rename from articles/interface.md rename to platform/interface.md diff --git a/articles/protocol.md b/platform/protocol.md similarity index 100% rename from articles/protocol.md rename to platform/protocol.md diff --git a/platform/toc.yml b/platform/toc.yml index a72a77bb..e8504b69 100644 --- a/platform/toc.yml +++ b/platform/toc.yml @@ -1,3 +1,7 @@ +- name: Overview +- href: protocol.md +- href: interface.md +- href: hardware-templates.md - name: Protocol - name: Binary Protocol href: ../protocol/BinaryProtocol-8bit.md @@ -12,5 +16,8 @@ - name: Data Interface - name: Python href: python.md -- name: Hardware templates - href: hardware-templates.md \ No newline at end of file +- name: Hardware +- name: Core Templates + href: hardware-cores.md +- name: Registered Devices + href: ~/protocol/whoami.md \ No newline at end of file diff --git a/tutorials/harp-behavior-dataacquisition.md b/tutorials/harp-behavior-dataacquisition.md new file mode 100644 index 00000000..400af545 --- /dev/null +++ b/tutorials/harp-behavior-dataacquisition.md @@ -0,0 +1,9 @@ +# Data Acquisition + +This is a placeholder for tutorials on acquiring data with the Harp Behavior Board. + +Content can be initially adapted from CF.Bonsai, specifically these links. +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/AnalogInput/AnalogInput.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/DigitalInput/DigitalInput.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/DIOInput/DIOInput.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/QuadratureEncoder/QuadratureEncoder.html \ No newline at end of file diff --git a/tutorials/harp-behavior-peripheralcontrol.md b/tutorials/harp-behavior-peripheralcontrol.md new file mode 100644 index 00000000..15acd477 --- /dev/null +++ b/tutorials/harp-behavior-peripheralcontrol.md @@ -0,0 +1,11 @@ +# Peripheral Control + +This is a placeholder for tutorials on controlling various peripherals. + +Content can be initially adapted from CF.Bonsai, specifically these links. +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/DigitalOutput/DigitalOutput.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/DigitalOutputPulse/DigitalOutputPulse.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/LEDToggle/LEDToggle.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/PWMToggle/PWMToggle.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/ServoMotorControl/ServoMotorControl.html +- https://fchampalimaud.github.io/cf.bonsai/workflows/HarpExamples/BehaviorBoard/ServoMotorToggle/ServoMotorToggle.html \ No newline at end of file diff --git a/tutorials/toc.yml b/tutorials/toc.yml index 6f85c0cd..599728af 100644 --- a/tutorials/toc.yml +++ b/tutorials/toc.yml @@ -2,4 +2,7 @@ - name: Software Installation href: setup.md - name: Firmware Update - href: firmware.md \ No newline at end of file + href: firmware.md +- name: Harp Behavior Board +- href: harp-behavior-dataacquisition.md +- href: harp-behavior-peripheralcontrol.md \ No newline at end of file From 1a3f150dc045bc95a75451df6f36d420c161aad4 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 12 May 2025 17:26:47 -0700 Subject: [PATCH 4/5] delete github actions recipe to force refresh of github actions --- .github/workflows/build.yml | 51 ------------------------------------- 1 file changed, 51 deletions(-) delete mode 100644 .github/workflows/build.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index 2adf1ce6..00000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,51 +0,0 @@ -# Builds and publishes the documentation website -name: Build docs - -on: - push: - branches: [ main ] - workflow_dispatch: - -concurrency: - group: build - cancel-in-progress: true - -permissions: - # Both required by actions/deploy-pages - pages: write - id-token: write - -jobs: - build: - runs-on: windows-latest - steps: - - uses: actions/checkout@v4 - name: Checkout - with: - submodules: recursive - - - name: Setup .NET Core SDK - uses: actions/setup-dotnet@v4 - with: - dotnet-version: 8.x - - - name: Custom Build Steps - run: .\build.ps1 - - - name: Setup MSBuild - uses: microsoft/setup-msbuild@v2 - - - name: Restore NuGet Packages - run: msbuild -t:restore src\harp\Bonsai.Harp.sln - - - name: Setup DocFX - run: dotnet tool restore - - - name: Build Documentation - run: dotnet docfx docfx.json - - - name: Upload GitHub Pages Artifact - uses: actions/upload-pages-artifact@v3 - - - name: Deploy to GitHub Pages - uses: actions/deploy-pages@v4 From 5121b58842a08f23ad28c311166eb66ec4411126 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 12 May 2025 17:33:31 -0700 Subject: [PATCH 5/5] restore github actions receipt to trigger refresh --- .github/workflows/build.yml | 51 +++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 .github/workflows/build.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 00000000..2adf1ce6 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,51 @@ +# Builds and publishes the documentation website +name: Build docs + +on: + push: + branches: [ main ] + workflow_dispatch: + +concurrency: + group: build + cancel-in-progress: true + +permissions: + # Both required by actions/deploy-pages + pages: write + id-token: write + +jobs: + build: + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + name: Checkout + with: + submodules: recursive + + - name: Setup .NET Core SDK + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 8.x + + - name: Custom Build Steps + run: .\build.ps1 + + - name: Setup MSBuild + uses: microsoft/setup-msbuild@v2 + + - name: Restore NuGet Packages + run: msbuild -t:restore src\harp\Bonsai.Harp.sln + + - name: Setup DocFX + run: dotnet tool restore + + - name: Build Documentation + run: dotnet docfx docfx.json + + - name: Upload GitHub Pages Artifact + uses: actions/upload-pages-artifact@v3 + + - name: Deploy to GitHub Pages + uses: actions/deploy-pages@v4