/*                                             -*- mode:C++; fill-column:100 -*- */
/**

\page Tutorials Tutorials

\section BlinkySketches Basic Output and Input

The \e 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.

 - \subpage blinky.cpp "The classic 'blink an LED' sketch"

 - \subpage blinky2.cpp "A more SFB-idiomatic 'blink an LED' sketch"

 - \subpage blinky3.cpp "An even smaller blinky sketch"

 - \subpage buttonled.cpp "Push the button to \e light the light"

 - \subpage buttonled2.cpp "Push the button to \e toggle the light"

\section OldioSketches 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 \ref PacketSketches), but it also possible to do
'good old-fashioned' a-byte-at-a-time serial input.  This section illustrates that 'legacy serial'
support.

 - \subpage helloworld.cpp "Print 'hello world'"

 - \subpage eChO.cpp "Demo byte-at-a-time reading"

\section PacketSketches 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 \c loop()
function, you create "reflexes" for your sketch, saying "Whenever \e this type of packet arrives,
call \e 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 \e 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:

 - \subpage pingpong.cpp "A minimal packet-in-packet-out sketch"

 - \subpage pingpong2.cpp "A sketch that pongs and pings"

 - \subpage blinkySync.cpp "The minimal SFB blink synchronization sketch"

 - \subpage forward.cpp "Responding to packets from just some places"

 - \subpage tee.cpp "Responding to all otherwise-unhandled packets"

\section ConsciouePacketSketches Conscious packet handling

If \ref OldioSketches may feel too low-level and rickety, like trying to build a house out of
toothpicks, well, perhaps \ref PacketSketches 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.

 - \subpage log.cpp "Logging via conscious packets"

 - \subpage brn.cpp "Shortcut baud rate negotiation"

(See \ref AdvancedPacketHandling for more examples.)


\section AlarmSketches Time-based event handling

Often a sketch needs to do something at some time in the future, and the core software provides the
\c 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 \e don't guarantee perfect accuracy: An alarm
handler \e 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.

 - \subpage alarm1.cpp "Setting a one-shot alarm"

 - \subpage alarm2.cpp "Using repeating alarms"

 - \subpage alarm3.cpp "Advanced alarms"

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

\section BasicEeprom 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.

 - \subpage eeprom1.cpp "Store a byte in EEPROM"

 - \subpage eeprom2.cpp "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 \e is it initialized?  See \ref AdvancedEeprom for more.

\section BasicSpeed Configuring the processor speed

Depending on how much actual \e 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.  

 - \subpage speed1.cpp "Set up a blinky to run at minimum processor speed"

 - \subpage speed2.cpp "Set up a sketch to run at a speed stored in EEPROM"

Note that these basic examples only change the processor speed during their \c setup() function.  
As an advanced technique, it \e 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 
\ref AdvancedSpeed for more information.

\cond
\section Installing Installation

The easiest way to get a sketch into an SFB is using the integrated
development environment, which runs on Linux, MacOS, and Windows.

 - \subpage linuxInstall "Linux Installation Tutorial"

 - \subpage macosInstall "MacOS Installation Tutorial"

 - \subpage windowsInstall "Windows Installation Tutorial"
\endcond

*/
