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

\page Tutorials Tutorials

\section FirstSketches First sketches

\subsection 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"

\subsection 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"

\subsection 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"

\subsection 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"


\subsection 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"

\subsection TimerSketches Using hardware timers

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

Hardware timers are a more advanced topic, primarily because (unlike with \c Alarms) the 'handler'
functions you write are executed with \e interrupts \e disabled, meaning that while your handler is
running, \e nothing \e 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!

 - \subpage timer1.cpp "Blink an LED using a hardware timer"

 - \subpage timer2.cpp "Configure a twelve hour clock"

 - \subpage timer3.cpp "Red light Green light"

 - \subpage timer4.cpp "A whiter shade of blinky"

\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

*/
