diff --git a/articles/collaborators.md b/articles/collaborators.md new file mode 100644 index 00000000..f07a5fe2 --- /dev/null +++ b/articles/collaborators.md @@ -0,0 +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 new file mode 100644 index 00000000..32b41451 --- /dev/null +++ b/articles/distributors.md @@ -0,0 +1,3 @@ +# Distributors + +Placeholder for links to vendors who are distributing Harp devices. \ No newline at end of file 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/python.md b/articles/python.md deleted file mode 100644 index 3b68b13d..00000000 --- a/articles/python.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -uid: python ---- - -[!include[harp-python](~/python/README.md)] diff --git a/articles/toc.yml b/articles/toc.yml index 96b8e561..3d8022fb 100644 --- a/articles/toc.yml +++ b/articles/toc.yml @@ -1,19 +1,6 @@ -- 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: 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..ef03256c 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 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](~/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 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/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 new file mode 100644 index 00000000..94c67b9d --- /dev/null +++ b/devices-page/harp-behavior.md @@ -0,0 +1 @@ +[!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 new file mode 100644 index 00000000..c9a5f8ba --- /dev/null +++ b/devices-page/toc.yml @@ -0,0 +1,8 @@ +- 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/docfx.json b/docfx.json index 6081d15c..92db7cb2 100644 --- a/docfx.json +++ b/docfx.json @@ -32,8 +32,12 @@ "articles/**.md", "articles/**/toc.yml", "tutorials/**.md", - "tutorials/**/toc.yml", + "tutorials/toc.yml", "protocol/**.md", + "platform/**.md", + "platform/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/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 new file mode 100644 index 00000000..d6173adf --- /dev/null +++ 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/platform/interface.md b/platform/interface.md new file mode 100644 index 00000000..df5e956f --- /dev/null +++ b/platform/interface.md @@ -0,0 +1,3 @@ +# Interface + +Placeholder for overview of the software interfaces. \ No newline at end of file diff --git a/articles/logging.md b/platform/logging.md similarity index 100% rename from articles/logging.md rename to platform/logging.md diff --git a/articles/message-manipulation.md b/platform/message-manipulation.md similarity index 99% rename from articles/message-manipulation.md rename to platform/message-manipulation.md index 69f0725d..651b2d55 100644 --- a/articles/message-manipulation.md +++ b/platform/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/platform/operators.md similarity index 100% rename from articles/operators.md rename to platform/operators.md diff --git a/platform/protocol.md b/platform/protocol.md new file mode 100644 index 00000000..c1b962a7 --- /dev/null +++ b/platform/protocol.md @@ -0,0 +1,3 @@ +# Protocol + +Placeholder for overview of the various Harp protocols. \ No newline at end of file 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..e8504b69 --- /dev/null +++ b/platform/toc.yml @@ -0,0 +1,23 @@ +- name: Overview +- href: protocol.md +- href: interface.md +- href: hardware-templates.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: logging.md +- href: message-manipulation.md +- name: Data Interface +- name: Python + href: python.md +- 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/toc.yml b/toc.yml index 8de88a1c..441c2683 100644 --- a/toc.yml +++ b/toc.yml @@ -1,6 +1,10 @@ -- name: Manual +- name: Overview href: articles/ -- name: Reference - href: api/ +- name: Platform + href: platform/ +- 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/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/setup.md b/tutorials/setup.md new file mode 100644 index 00000000..f1f4f947 --- /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](../platform/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..599728af --- /dev/null +++ b/tutorials/toc.yml @@ -0,0 +1,8 @@ +- name: Getting Started +- name: Software Installation + href: setup.md +- name: Firmware Update + href: firmware.md +- name: Harp Behavior Board +- href: harp-behavior-dataacquisition.md +- href: harp-behavior-peripheralcontrol.md \ No newline at end of file