README.md

# FLIGHT Simulator

The FLIGHT simulator is a Linux program that appears to be the FLIGHT
installation and responds to scripting commands. It is structured as
follows:

  - [fsimulator](fsimulator): the main executable for running the simulator.
  - [graphics](graphics): the graphics library for displaying the simulated
  state of FLIGHT.
  - [client](client): a simple test client for interacting with the simulator.
  
The intended use of the simulator is to test and visualize what the
[FlightGui](../FlightGui) UI is doing. It allows you to test its
output without requiring a full FLIGHT installation. This lets you
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
Flyers and displays them graphically.

![The high level flow of the simulator is summarized in this diagram.](SimulatorFlow.png)

Currently, the simulation component of the simulator is complete but
the graphics are unfinished.

## Python API

Fractal Flyers provide 3 Python functions to control their lights and wings:

``` Python
wing_leds(LEFT|RIGHT, (r, g, b), (r, g, b,), (r, g, b,))
body_leds((r, g, b)
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.