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

\page AdvancedExamples Advanced Examples

\section AdvancedPacketHandling Advanced packet handling

In the usual flow of SFB affairs, packets are input from any of the four faces and are reacted to,
and output packets are sent out to any of the four faces, from packet handlers, Alarm handlers, or
the loop() method.  But sometimes more fine-grained control over packet handling is needed, and the
core software provides more advanced mechanisms for that purpose.

 - \subpage trigger.cpp "Reacting to conscious packets"

 - \subpage fifthdirection.cpp "Writing a note to self"

 - \subpage reorder.cpp "Reacting to out-of-order packets"

 - \subpage hallucination.cpp "Creating packets in memory"

\section QLED Controlling the built-in LEDs without delays

For debugging, display, or just fun, we often want to blink the onboard LEDs in response to events.
The 'good old-fashioned way' to blink an LED is (1) Turn it on, then (2) Delay for a while, then (3)
turn it off, but if we do that -- step (2) specifically -- inside a packet (or alarm) handler, we
can run into trouble.  Since only \e one \e handler \e runs \e at \e a \e time, \b all handler
functions (packet or alarm) need to be relatively quick, to give the other handlers a chance.  But
calling #delay() is the \e opposite of being quick.

The #QLED object (an instance of #SFBQLED) provides a way to schedule LED 'on' and 'off' 'events'
without calling #delay().

 - \subpage qled1.cpp "Blink LEDs from a packet handler without blocking"



\section AdvancedEeprom Advanced EEPROM usage

In the basic tutorials, \ref BasicEeprom illustrated the primary functions used for accessing the
EEPROM.  Here we touch on one additional function -- #eepromWait() -- and look at an advanced
mechanism for initializing EEPROM data.

 - \subpage eeprom3.cpp "Waiting for EEPROM writes to finish"

 - \subpage eeprom4.cpp "Use a checksum to validate/initialize EEPROM"

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

\section ProfileSketches Profiling sketch behavior

As you add more and more behavior to your sketch, as you pile on more and more alarm and packet
handlers, you will at some point begin to overtax the hardware and performance will suffer, and
packets will get dropped, or alarm handlers will run later than scheduled, or the like.  To help
determine where time is actually being consumed, the core software provides a basic 'profiling'
system consisting of two objects, a low-level object called #Ticker, and a higher-level object
called #Profile.  

The #Ticker assigns microseconds to one of several broad categories (see #SFBTickerCategories) like
'packet handler' or 'alarm handler', which are just what you would expect, or 'background
processing', which includes time spent in the \c setup() and \c loop() functions as well as whatever
isn't categorized somewhere else.  Also, there are three categories (e.g., #TICKER_SKETCH0) reserved
for whatever execution-time-counting needs you may have.  \c Ticker, an instance of #SFBTicker, is
built into the core software; its primary limitation is that its microsecond-based counters overflow
after about an hour, just like #micros().

The #Profile operates with millisecond resolution, so it can count well over a month of time without
overflowing, using the same set of #SFBTickerCategories.  It gathers data from #Ticker and uses an
alarm to reset #Ticker regularly to keep it from overflowing (so if #Profile is active, results
returned from SFBTicker::getUsec(u32) may be somewhat hard to interpret -- use
SFBProfile::getMsec(u32) instead).

 - \subpage profile1.cpp "Demonstrate the low-level 'Ticker'"

 - \subpage profile2.cpp "Report a time profile of a sketch"

 - \subpage profile3.cpp "Use a custom profile category"

\section AdvancedSpeed Changing the processor speed on the fly

The examples in \ref BasicSpeed only demonstrated changing the processor speed in the #setup()
function.  It \e is possible to change the #Processor speed at any point(s) during a single sketch
execution, but the sketch writer should be aware of some limitations and warnings before they try to
do so.  See SFBProcessor::setCode() for the details.

 - \subpage speed3.cpp "Change processor speed on the fly"

 - \subpage speed4.cpp "Dynamic throttling of processor speed"

\section CustomZHandlers Extending printf/scanf with 'custom Z handlers'

Traditional printf and scanf functions excel at handling data using built-in formats such as
decimal.  The printf/scanf-style functions in the SFB core, such as ::facePrintf and ::packetScanf,
have an extension called 'custom Z handlers', which enable you to define your own
::CustomPrintfHandler (which see, for details) and/or ::CustomPacketScanfHandler, and then handle
formats involving mixtures of traditional formats and your custom format.

 - \subpage zformat1.cpp "Custom Z handlers to double a char"

 - \subpage zformat2.cpp "Formatted I/O of 2D coordinates using custom Z handlers"

 - \subpage zformat3.cpp "Custom Z handlers using recursion"

\section PWMSketches Using the hardware PWM module

--TO COME--

\section PowerSketches Controlling power

--TO COME--


*/
