Jun 2012  Paul Schimpf
Feb 2013  Added citation for Embedded Systems article
Aug 2015  Added ISR and mutex notes

-----------------
To install ARTK:
-----------------
Create a directory called ARTK under your Arduino library directory.
Extract the contents of ARTK.zip into that directory.

-----------------
To test ARTK:
-----------------
Create a directory somewhere called ARTKtestMega or ARTKtestUno (depending on
whether you have an Arduino with more or less than a 64kbyte memory space).

Copy the corresponding .ino file into that directory.

Start the Arduino environment and load that sketch.

Compile and Upload to your Arduino.

Open your Serial Monitor (on the Tools menu).

You may need to press the Arduino reset button.

Compare the Monitor output to the contents of the file outputMega.txt 
or outputUno.txt

-----------------
What next?
-----------------
Read all the comments and code in the test file carefully and make sure you
understand why the output looks the way it does.

Read the usage comments at the top of ARTK.h file.

Read the short user manual. This manual is published in the International Journal
for Embedded Systems:

Paul H. Schimpf, "ARTK: a compact real-time kernel for Arduino,"
Int. J. Embedded Systems, Vol. 5, No. 1/2, pp. 106-113, 2013

Please refer to the above publication if you publish an article describing a system 
that makes use of ARTK.

Experiment.

Try programming the dining philosophers problem in ARTK. Implement each philosopher
as a task, and each fork (or chopstick, if you prefer) as a semaphore that can support
a single entry. You can use ARTK_Sleep to simulate eating and thinking. For a bit of 
extra challenge implement all your philosophers using the same root function. On an 
Uno don't try to program more than 3 philosophers.

Is deadlock a problem with dining philosophers in ARTK?  Not if all your
philosophers have the same priority. The reason deadlock will never happen
in this case is that, unlike some kernels, ARTK does NOT timeslice tasks 
with equal priority. When one such task is pre-empted, or voluntary relinquishes
the processor with ARTK_Yield(), it goes to the end of a round-robin queue
with other tasks at the same priority level. You can simulate what can happen
in a time-slicing kernel by having your philosophers call ARTK_Yield() in 
between obtaining their right and left forks (or chopsticks). Then try and find a 
solution that fixes the deadlock without removing the Yield (hint: try having one
philosopher pick up the forks in the opposite order of the other philosophers).

Try using ARTK tasks in your next Arduino embedded systems project,
but only if concurrent execution makes sense for it.

-----------------
Why no mutex construct?
-----------------
Mainly because ARTK is designed to be simple. Note that you can implement a simple
mutex with a semaphore initialized to 1. A more sophisticated mutex construct is
not really necessary unless you need your kernel to perform priority inheritance
to fix priority inversion, which requires a construct that keeps track of the "owning" 
task. ARTK doesn't attempt to detect deadlock either. It is up to you to ensure it does
not occur. That really isn't very hard for simple systems.

-----------------
Some notes about ISRs
-----------------
When used with any real-time kernel, ISRs should follow these rules:
1) They should be short and quick. If there is significant business to be done in 
   response to the interrupt, signal a task through a semaphore and return.
2) They should never ever block, and thus should never wait on a semaphore

With ARTK there is an additional rule:

3) ISRs used with ARTK must be re-entrant. In particular, any static variable that is
tracking some kind of state in the ISR should be modified PRIOR to signaling a semaphore 
(which is the only kernel call that you should ever make from an ISR).

This is because ARTK does not require that it be notified upon ISR entrance and exit. 
It is thus not aware that an ISR is executing, which happens within the context of the
interrupted task. 
A big reason that some systems require the kernel be notified of entrance to an ISR is so 
that context switches from things like signaling semaphores can be deferred until after 
the ISR exits. ARTK does not defer these, and interrupts will be reenabled on a context
switch. That means that the context switch from signaling a semaphore will happen before 
the ISR returns, which in turn means that the ISR might be re-entered.

This approach makes coding easier but comes at the cost of possible ISR re-entrance.
I have considered changing this to the more typical approach, but it would be a significant
effort and the footprint for ARTK would grow. In addition, the ARTK approach of not
deferring task switches makes for some good educational discussions in a course in which
I use it.

-----------------
It's Free
-----------------
ARTK is open source, in keeping with the spirit of Arduino. Please respect the 
GPL license terms, which you can find in the file gpl.txt. ARTK is also free.
I developed this on my own time and received no compensation for doing so. If 
you find it useful feel free (or not, it is entirely up to you) to send a PayPal 
contribution to: 

pay.pschimpf@gmail.com 
