Draft for site reorganization

articles/collaborators.md

@@ -0,0 +1,3 @@
+# Collaborators
+
+Placeholder for links to collaborators and acknowledgement of contributions.

articles/distributors.md

@@ -0,0 +1,3 @@
+# Distributors
+
+Placeholder for links to vendors who are distributing Harp devices.

articles/about.md → 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.

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

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.
+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).

devices-page/harp-behavior.md

@@ -0,0 +1 @@
+[!include[Harp Behavior Board](~/src/device.behavior/README.md)]

devices-page/harp-soundcard.md

@@ -0,0 +1 @@
+[!include[Harp Sound Card](~/src/device.soundcard/README.md)]

devices-page/harp-timestamp-generator-gen3.md

@@ -0,0 +1 @@
+[!include[Harp Timestamp Generator Gen3](~/src/device.timestampgeneratorgen3/README.md)]

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

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"
         ],

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.<device>`. For instance, for the [Harp Behavior](xref:Harp.Behavior) board, you should find the following package:
-
-<p><img alt="Installing a Harp device package" src="~/images/behavior-package.png" style="max-height:450px;object-fit:contain" /></p>
-
-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)
+[!include[what-is-harp](articles/what-is-harp.md)]

platform/hardware-cores.md

@@ -0,0 +1,3 @@
+# Hardware
+
+Placeholder for article on the hardware cores (ATxmega, Pico)

platform/hardware-templates.md

@@ -0,0 +1,3 @@
+# Hardware
+
+Placeholder for overview of the hardware templates.

platform/interface.md

@@ -0,0 +1,3 @@
+# Interface
+
+Placeholder for overview of the software interfaces.

articles/message-manipulation.md → 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.
 

platform/protocol.md

@@ -0,0 +1,3 @@
+# Protocol
+
+Placeholder for overview of the various Harp protocols.

platform/python.md

@@ -0,0 +1,5 @@
+---
+uid: python
+---
+
+[!include[harp-python](../python/README.md)]

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

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/

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

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

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.<device>`. For instance, for the [Harp Behavior](xref:Harp.Behavior) board, you should find the following package:
+
+<p><img alt="Installing a Harp device package" src="~/images/behavior-package.png" style="max-height:450px;object-fit:contain" /></p>
+
+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.

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