Commit 4dc59eae authored by Philip Levis's avatar Philip Levis
Browse files

Update documentation for Python API.

parent 9587b08d
......@@ -17,14 +17,23 @@ test whether the UI is producing correct scripts and debug more easily.
## Operation
Normally, each Fractal Flyer in FLIGHT is plugged into a computer with
USB and appears in two ways, as a serial port presenting a Python
read-eval-print-loop and as a removeable USB drive that you can store
Python code on. When the FLIGHT simulator boots, it creates 76 entries
in the local file system (named FIFOs) that act like serial ports and
76 directories that you can copy Python code into. It starts up 76
Python interpreters which receive Python scripting commands from the
simulated serial ports. These 76 interpreters send commands to a
server process, which simulates the lights and motion of the Fractal
USB. Each Flyer appears to the computer in two ways, as a serial port
presenting a Python read-eval-print-loop and as a removeable USB drive
that you can store Python code on.
The FLIGHT simulator recreates this behavior. When it boots, it
creates 76 entries in the local file system (named FIFOs) that act
like serial ports. These simulated serial ports are connected to
Python interpreters that provide the same API as a Fractal Flyer (see
below). The simulator also creates 76 directories that you can copy
Python code into, code which is accessible to the Python
interpreters. Just like the Fractal Flyers, if you copy new code to
the directory, the Python interpreter reboots: the simulator registers
for changes to the directory with `inotify(7)` and restarts the
corresponding interpreter process when it receives a notification.
These 76 interpreter processes send commands to a server process over
a network socket, which simulates the lights and motion of the Fractal
Flyers and displays them graphically.
![The high level flow of the simulator is summarized in this diagram.](SimulatorFlow.png)
......@@ -45,13 +54,16 @@ wing_angle(LEFT|RIGHT, angle)
Where r g and b are 0-255 and angle is -90.0 - 90.0.
The assumption is the LED changes are near-instantaneous. The angle
change, however, may take time. The FF is smart enough to know its
current wing position and velocity and just try to move to the most
recent angle command. So, suppose the left wing is at 0 and you call
wing_angle(LEFT, -20),the left wing will start to lower to
-20. Suppose, when it is at -10, you call wing_angle(LEFT, -30). It
will keep on lowering until it reaches -30. If, when it is at -25, you
call wing_angle(LEFT, 10), it will slow and stop, then start moving
to 10. This will all occur on the firmware.
This API assumes that the LED changes are near-instantaneous. The wing
angle change, however, may take time. Each Fractal Flyer has a local
control loop that moves the wings to the last specified position in a
stable way.
For example, suppose the left wing is at 0 and a script calls
`wing_angle(LEFT, -20)`. The left wing will start to lower to
-20. Suppose, when it is at -10, the script calls `wing_angle(LEFT,
-30)`. The wing will keep on lowering until it reaches -30. If, when
it is at -25, the script calls `wing_angle(LEFT, 10)`, it will slow
and stop, then start moving to 10. The firmware takes care of all of
this logic.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment