Data flow

At a very high level, this app is essentially a stream processor, taking in a stream of sensor readings, and generating a stream of appropriate motor commands.

You might not be fiddling with the app at this level - it's mostly the physics and maths of the infrastucture code - but it's fun to fully understand how the bot bots. :)

index.js:

hardware
  .pipe(interpretSensors)
  .pipe(brains)
  .pipe(setMotorSpeeds)
  .pipe(hardware);

This document mainly expands on the interpretSensors stream and the setMotorSpeeds stream. A lot of the interesting stuff happens in the 'brains' stream, and consequently in the Behaviours system.

interpretSensors, brains and setMotorSpeeds are all transform streams - they modify the data along the way.

hardware

Defined in /streams/hardware.js

This is the source and sink of the data streams of the bot. It is implemented as a node.js duplex stream, just to be all fancy. It puts objects containing sensor data into the stream, every config.clock milliseconds. Also, as a sink, it listens for motor commands, and in turn (hehe) causes the motors to move.

// Sample data read from sensors, pushed into the stream every config.clock milliseconds
{
  ticks: { left: 0, right: 0 }, // buffered up since the last time
  batteryVoltage: 8.4  // volts
}

interpretSensors

Defined in /sensors/index.js, via /streams/sensors.js

This handles receiving sensor data from the hardware, and interprets it for consumption by the brain. For example, this stream infers the bots odometry from the tick data. There's more detailed information about odometry Read more about it here.

Remote control commands, and commands from the UI are also considered to be sensors, as defined in remote-command.js. Some sensors, like the virtual-bumpers need not even physically exist.

brains

The brains stream is described in a different document, so refer to that. It's worth pointing out here that after interpretSensors, the brain receives objects that looks like the following:

{
  ticks: { ... },
  obstacleSensors: { ... },
  odometry: {
    x: 123,
    y: 456,
    phi: 0
  }
}

and the brain is expected to output objects that look as follows:

{
  velocity: 123,
  rotation: 456
}

which is the format that setMotorSpeeds expects.

setMotorSpeeds

Defined in /streams/motor-command.js

This reads the desired velocity and rotation value from the brain, and converts it to appropriate PWM levels for the left and right wheels' motors. More details about the maths behind this can be found in the kinematics page.