Update install docs.

ceed/view/teensy_estimation/readme.md

@@ -1,4 +1,36 @@
 Teensy Frame Estimation
 =======================
 
-`arduino-1.8.13/hardware/teensy/avr/cores/teensy4/usb_rawhid.c` edit `TX_NUM` to 1.
+The Teensy is used to help Ceed identify when a frame was rendered for two frames by the GPU, requiring
+Ceed to drop a frame. See more details in the [docs](https://matham.github.io/ceed/blueprint.html).
+
+Programming Teensy
+------------------
+
+If this is a new Teensy device, it'll need to be re-programmed. The easiest way is to download the
+pre-compiled
+[teensy_estimation.ino.hex file](https://github.com/matham/ceed/blob/master/ceed/view/teensy_estimation/teensy_estimation.ino.hex).
+Then, following the instructions and using the [Teensy Loader App](https://www.pjrc.com/teensy/loader.html),
+program the Teensy with the hex file.
+
+If something has changed and the hex file needs to be recompiled, then follow the
+[instructions](https://www.pjrc.com/teensy/teensyduino.html) to install Teensyduino by installing the
+[Arduino IDE](https://www.arduino.cc/en/software) and then the
+[Teensyduino add-on](https://www.pjrc.com/teensy/td_download.html).
+
+Then, get and open the source
+[teensy_estimation.ino file](https://github.com/matham/ceed/blob/master/ceed/view/teensy_estimation/teensy_estimation.ino).
+Then, locate the ``teensy4/usb_rawhid.c`` file, it'll be located under the arduino installation
+(e.g. ``arduino-1.8.13/hardware/teensy/avr/cores/teensy4/usb_rawhid.c``). You'll have to make three changes in the file
+to improve latency:
+
+* change ``#define TX_NUM   4`` to ``#define TX_NUM   1``,
+* in the function ``usb_rawhid_recv`` change the line ``if (systick_millis_count - wait_begin_at > timeout)  {`` to
+  ``if (systick_millis_count - wait_begin_at >= timeout)  {``
+* similarly, in the function ``usb_rawhid_send`` change the line ``if (systick_millis_count - wait_begin_at > timeout) return 0;``
+  to ``if (systick_millis_count - wait_begin_at >= timeout) return 0;``
+
+Then after saving, in the Arduino IDE ensure that the USB type under tools is set to "Raw HID". And that for the
+board the Teensy 4.1 is selected. And finally, under port, select the Teensy device so it can be programmed.
+Finally, compile ``teensy_estimation.ino`` and upload it to the Teensy as described in the
+[docs](https://www.pjrc.com/teensy/td_usage.html).

doc/source/apps/optics_app.rst

@@ -1,3 +1,5 @@
+.. _optics-app:
+
 .. automodule:: ceed.tools.optics
    :members:
    :show-inheritance:

doc/source/blueprint.rst

@@ -1,9 +1,15 @@
+.. _ceed-blueprint:
+
 System Blueprint
 ================
 
-The goal of the system is to optically stimulate brain tissue with temporal-spatial precision and to
-simultaneously record the voltage of the neurons in the tissue being stimulated with a dense
-electrode array (e.g. 256 electrodes).
+The goal of the system mostly controlled by Ceed is to:
+
+1. visually locate neurons in the brain tissue,
+2. optically stimulate the tissue with temporal-spatial precision,
+3. simultaneously record the voltage of the neurons in the tissue
+   being stimulated with a dense electrode array (e.g. 256 electrodes),
+4. temporally align the optical stimulation with electrode activity in a single data file post-hoc.
 
 The overall system looks as follows
 
@@ -17,33 +23,42 @@ Users create spatial patterns in ceed, and associate temporal functions with the
 E.g. we may want to stimulate a single neuron with a sine wave, so we draw a circle around
 it and vary the circle's intensity temporally using a sine function.
 
-Ceed uses Python 3 and Kivy for the GUI. We have a dedicated Ubuntu 18 computer that runs
-the software.
+Ceed generates the projector RGB output, as well as a synchronization signal recorded by MCS.
+After the experiment, Ceed temporally aligns and merges the MCS electrode data with the
+spacial-temporal patterns it generated.
+
+Ceed uses Python 3 and Kivy for the GUI. We have a dedicated Ubuntu computer that runs
+ceed.
 
 VPixx
 -----
 
-To stimulate the tissue, we use a VPixx projector, that can output frames upto 1440 Hz in
-greyscale or 500 Hz in RGB. Ceed generates the frames, which is sent to the projector,
-and then through a lenses until it reaches the tissue.
+To stimulate the tissue, we use a `VPixx projector <https://vpixx.com/>`_ that can output
+frames upto 1440 Hz in greyscale or 500 Hz in RGB. Ceed generates the frames, which is sent
+to the projector, and then through the lenses until it reaches the tissue.
+
+The VPixx controller is responsible for converting the corner pixel RGB 24-bit value of each
+frame into a 5v 24-bit port logic output. Upto 16 of the ports are connected to and recorded
+by the MCS controller. Ceed especially generates a pattern that it subsequently uses to
+temporally align the two systems.
 
 Multichannel Systems (MCS)
 --------------------------
 
-The MCS system is the electrode recording system and is responsible for
-recording any brain activity in the tissue. This is a dense electrode array recording from
-many cells simultaneously.
+The `MCS system <https://www.multichannelsystems.com/>`_ is the electrode recording system
+and is responsible for recording any brain activity in the tissue. This is a dense electrode
+array, recording from many cells simultaneously.
 
 This system is controlled by MCS provided software that controls the electrode arrays
-and records the electrode data to files.
+and records the electrode data to ultimately HDF5 files.
 
 Camera
 ------
 
-We use a Thor camera to capture light emitted by the tissue. In a typical experiment,
-first we broadly stimulate the tissue with light to see where the cells are present
-as captured by the camera. Then, we design stimulus in Ceed to stimulate the desired cells
-and observe the resulting electrical activity.
+We use a `Thor camera <https://www.thorlabs.com>`_ to capture light emitted by the tissue.
+In a typical experiment, first we broadly stimulate the tissue with light to see where
+the cells are present as captured by the camera. Then, we design stimulus in Ceed to
+stimulate the desired cells and observe the resulting electrical activity with MCS.
 
 Data alignment
 --------------
@@ -62,6 +77,39 @@ Networked PCs
 Because the linux PC is used to generate the Ceed frames which is output to the projector,
 we cannot use that computer to view the camera images. When we tried attaching multiple
 screens, the GPU periodically missed frames, we suspect because the the two screens may not
-have supported the precise frame rate. Consequently, we use the Windows computer running
-the MCS software to control the Thor camera, display the images to the user and then
-pass them over the network to the Linux/Ceed PC.
+have supported the precise frame rate. Consequently, we use the Windows computer, already
+running the MCS software to control the Thor camera, display the images to the user and then
+pass them over the network to the Linux/Ceed PC for drawing.
+
+
+Teensy
+------
+
+Although Ceed takes special care to reduce per-frame CPU, sometimes the CPU-GPU results in a
+frame taking two or more render cycles to render. E.g. at 120Hz, a single frame lasts 8.33ms.
+Sometimes the computer will miss the 8.33ms deadline and display the current frame twice before
+displaying the next frame. This effectively shifts all subsequent frames forward by 8.33ms,
+potentially disrupting the stimulated circuitry temporal patterns.
+
+We can recognize such long frames based on internal timing with high confidence, but
+only after a few frames have passed. The `Teensy <https://www.pjrc.com/teensy/>`_,
+running in USB-interrupt mode at 8+ kHz, reduces the number of bad frames (typically to 2,
+the number of frames buffered) by giving Ceed quick feedback when it drops a frame. It
+notices the dropped frames by monitoring the above-mentioned VPixx 24-bits.
+
+Additionally, Ceed uses the Tennsy built-in LED to indicate the experiment status since
+the PC monitor is used entirely to project the patterns and cannot provide such feedback.
+
+The Teensy is optional and can be turned OFF within Ceed if it's not available.
+
+Microscope
+----------
+
+The microscope, including the dichroic mirror controls the flow of light from the projector
+to the issue and from the tissue to the camera.
+
+The dichroic mirror reflects down the colors of light emitted by the projector onto the
+tissue. The tissue also emits different color wavelengths, which is passed through by the
+mirror to the camera.
+
+See :ref:`microscope-optics` for a full specification of the Microscope.

doc/source/conf.py

@@ -36,6 +36,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.intersphinx',
     "sphinx_rtd_theme",
+    "sphinx.ext.autosectionlabel",
 ]
 
 intersphinx_mapping = {

doc/source/getting_started.rst

@@ -4,16 +4,40 @@ Getting Started
 Introduction
 -------------
 
-Ceed is an in vitro experiment that stimulates brain slices and records
-their activity.
+Ceed is a Python based application to help run in-vitro experiments that
+stimulates brain slices and records their activity.
+
+Ceed is the user interface for describing and running the experiments.
+The overall system is described in :ref:`ceed-blueprint`.
+See the :ref:`ceed-guide` for the Ceed specific guide.
+
+Complete developer API documentation is at :ref:`ceed-root-api`.
 
 Usage
 ------
 
-To use Ceed, you first need to install it, see :ref:`install-ceed`.
+Ceed is normally run on the PCs connected to the required hardware described
+in :ref:`ceed-blueprint`. However, it can also be run in a demo-mode on
+a Windows/Linux PC without any additional hardware.
+
+To run Ceed, you first need to install it as a python package; see :ref:`install-ceed`.
 
-After it's installed, it is run through the main module. For example::
+After it's installed, you can run it by running the ``run_app`` file, or by entering
+``ceed`` in the terminal. For example::
 
-    python -m ceed.main
+    python ceed/run_app.py
+    # or if you are in the python enviroenment where ceed was installed, just
+    ceed
+
+A compiled executable can be downloaded from the
+`release page <https://github.com/matham/ceed/releases>`_ for Windows. This can be run
+as a demo, without installation.
+
+Configuration
+-------------
 
-Complete API documentation is at :ref:`ceed-root-api`.
+Ceed can be fully configured through a
+`yaml file <https://github.com/matham/ceed/blob/master/ceed/data/CeedApp_config.yaml>`_.
+This file is normally in the data directory under ceed, where ceed is installed.
+Documentation for all the configuration options is listed in the `CEED Config
+section <#CEED Config>`_.

doc/source/guide.rst

@@ -0,0 +1,5 @@
+.. _ceed-guide:
+
+Ceed Guide
+==========
+

doc/source/index.rst

@@ -8,18 +8,19 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   getting_started.rst
    blueprint.rst
    installation.rst
-   getting_started.rst
+   guide.rst
 
-   apps/apps.rst
    config.rst
 
-   optics/optics.rst
+   example_code/example_code.rst
 
+   apps/apps.rst
    api/api.rst
 
-   example_code/example_code.rst
+   optics/optics.rst
 
 
 * :ref:`genindex`