Tutorials

First sketches

Basic Output and Input

The first thing we want is output; we want to say "We're alive!" Blinking an LED is the traditional first step. Eventually we'll also want input; a way to sense the outside world. Reading the state of a push button is a common first step there.

• The classic 'blink an LED' sketch

• A more SFB-idiomatic 'blink an LED' sketch

• An even smaller blinky sketch

• Push the button to light the light

• Push the button to toggle the light

Traditional serial communications

For more intensive input and output, serial communications -- sending streams of bytes in and out of an SFB -- can be very effective. Now, the SFB has powerful 'packet handling' facilities to make 'event-driven input packet handling' easy (see Reflex packet handling), but it also possible to do 'good old-fashioned' a-byte-at-a-time serial input. This section illustrates that 'legacy serial' support.

• Print 'hello world'

• Demo byte-at-a-time reading

Reflex packet handling

Byte-at-a-time serial input processing quickly becomes unwieldy, particularly given we can have up to four faces feeding us serial input simultaneously. The SFB 'packet system' is designed to allow input operations to take place at a higher level. The packet system allows a sketch to deal with entire lines of text or data at once. Instead of endlessly 'polling' for bytes inside a loop() function, you create "reflexes" for your sketch, saying "Whenever this type of packet arrives, call that function to handle it." Reflex packet handling is the SFB's 'native tongue' -- it is what SFB's use, by default, to talk to each other, and it underlies the 'code flow protocol' that allows SFB's to download sketches from host computers and each other.

Using the packet system in your sketch can feel quite strange at first, because the sketch never actually reads any input. What is really happening is that the core software is collecting input bytes that arrive from the outside world, and storing them in memory. The sketch isn't bothered unless a complete line of text -- a complete 'packet' -- is available, and the sketch has expressed an interest in packets of that type.

Consider these examples:

• A minimal packet-in-packet-out sketch

• A sketch that pongs and pings

• The minimal SFB blink synchronization sketch

• Responding to packets from just some places

• Responding to all otherwise-unhandled packets

Conscious packet handling

If Traditional serial communications may feel too low-level and rickety, like trying to build a house out of toothpicks, well, perhaps Reflex packet handling may feel too uncertain and out-of-control, like trying to sip tea on a racing horse. "Conscious packet handling" falls somewhere in between -- it works with whole packets, not a byte at a time, but avoids all the automatic baud rate negotiation and background packet handling.

• Logging via conscious packets

• Shortcut baud rate negotiation

Time-based event handling

Often a sketch needs to do something at some time in the future, and the core software provides the Alarms system to make that easy. You write an 'alarm handler' function, and create and set an alarm, and when the alarm goes off your alarm handler gets called.

Alarms can be used for one-shot or repeating events, they can be canceled, or reset for a different time, before or after they have gone off, and dozens of them are available for sketch use. Alarms provide resolution down to the millisecond, but they don't guarantee perfect accuracy: An alarm handler may be called right on the millisecond for which it was scheduled, but it may run one or more milliseconds later, depending on how busy the system is.

• Setting a one-shot alarm

• Using repeating alarms

• Advanced alarms

Using hardware timers

As an advanced technique, if you need more accurate timing than the Alarms system provides, you can use a hardware timer. There are three hardware timers specifically reserved for sketch use, named Timer1, Timer2, and Timer3. In addition, there is a fourth timer (named Timer4, naturally) also available, but that hardware is shared with the hardware PWM (Pulse Width Modulation, see PWMSketches) system, so a single sketch cannot use both hardware PWM and Timer4.

Hardware timers are a more advanced topic, primarily because (unlike with Alarms) the 'handler' functions you write are executed with interrupts disabled, meaning that while your handler is running, nothing else is happening -- no input is being read, no output is being shipped, the millis() clock isn't ticking, and so on. So you need to keep your timer handler functions relatively short and simple as much as possible.

But, that said, don't be afraid! Sometimes a hardware timer is just the right tool for the job!

• Blink an LED using a hardware timer

• Configure a twelve hour clock

• Red light Green light

• A whiter shade of blinky