Write documentation for experiment and schema

[ederancz]

I suggest to write incrementally with the issues we encounter. Here are the first few issues in order of urgency.

1. Unit conversions for the most important H1 and H2 registers

flowY to degrees - What is the sensor resolution (range 100-12000 cpi, but I can't find it where is it set). pulse interval to motor displacement in degrees register H2#42 During stationary ball, pulse interval toggles between 20000 and 0, with no motor movement. This is weird as this should be a signed value, with the sign representing rotation direction. motor encoder to motor position in degrees register on H2

2. Gain definitions.

Gain calculation equations from Andrew below make sense superficially. But unclear what the units are (flowX, flowY, rotary, playback). Ultimately we want to say motor gain = W and visual gain = Z of optical flow sensor (in degrees). Here are the definitions from Andrew for reference:

Hierarchy
Global
-runGain
    Block
    -blockGain
        Visual
        -flowXToVisual etc…

Definitions:
---Visual
(runGain * blockGain) * (flowX*a + flowY*b + rotary*c + playback*d) = amount to move visual field
---Motor
(runGain * blockGain) * (flowX*e + flowY*f + playback*g) = amount to move motor

3. H2 register documentation with units and range

4. H1 register documentation with units and range

5. Optical flow sensor smoothing

Is there any smoothing applied? Where is it in the workflow and how to change it (no need for separate external parameter in the yml file).

[EleonoraAmbrad]

part of the schema documentation issue, but just encountered: when setting the runThreshold parameters to induce halts, we were wondering about the exact definition of the decayTimestep and the runThresholdDecay. From what we understood, the runThreshold is modified by subtracting position units from it, at a rate controlled by the decayTimestep, but when does this stop? Also, what is the exact function of these two parameters?

[RoboDoig]

You can check these definitions in the schema itself.

As the animal runs a value is accumulated which is compared to the threshold value, when it exceeds this value a halt is produced. If the animal doesn't run, the accumulated value decays back to 0.

decayTimestep: the time in seconds between each decay towards 0 runThresholdDecay: the amount of decay towards 0 applied on each decayTimestep

The units of runThresholdDecay sort of depends what is contributing towards the accumulation of running. This is usually the flow sensors - and in this case the units are related to flow sensor units.