Tutorials

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

(See Advanced packet handling for more examples.)

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

If the no-less-than-millisecond resolution or possible delays of Alarms are a problem for your timing application, see Using hardware timers for an alternative!

Using the EEPROM

When a board loses power, the contents of its RAM becomes unreliable (at least in general). Usually that's no problem, because when the board is powered back up, the setup() function will run again, and whatever needs to be initialized will get initialized.

But often, there is information that one would like to preserve for the future, power-losses, reboots, or whatever notwithstanding. It might be nice to know how many times the board had been rebooted, just to make up an example (see getBootBlockBootCount).

Enter the EEPROM. EEPROM stands for 'Electrically Erasable Programmable Read-Only Memory', which is an extremely long-winded way of saying 'persistent storage', like a hard drive.

• Store a byte in EEPROM

• Store a multibyte value in EEPROM

Persistent data is good because it doesn't have to be be initialized in the setup() function. But then, when is it initialized? See Advanced EEPROM usage for more.

Configuring the processor speed

Depending on how much actual computing you need your board(s) to do, running the processor at full speed --- which is its default behavior --- might be more than you need. If your sketch isn't too demanding, by setting up the processor to run a slower speed, your board will use less power and run cooler.

• Set up a blinky to run at minimum processor speed

• Set up a sketch to run at a speed stored in EEPROM

Note that these basic examples only change the processor speed during their setup() function. As an advanced technique, it is possible to change processor speed 'on the fly', but there are some significant limitations and warnings you should be aware of before you try. See Changing the processor speed on the fly for more information.