#lang scribble/manual 
  @(require "firmata.rkt" scribble/eval (for-label racket "firmata.rkt"))
  @(require planet/scribble)
  @defmodule["firmata.rkt"]

  @title{DrFirmata -- The Arduino Micro-controller Interface}
  @section{Introduction}
 
  The DrFirmata firmata provides abstractions under the form of functions which allow you to program a micro-controller via the serial port of a computer.
  The library uses the Firmata protocol for communicating with the micro-controller.  
  Firmata is a generic protocol popularized by the Arduino platform which supports both input and output for digital and analog pins.
  With this library you can develop small applications on a micro-controller without having to write any software on the host computer for the micro-controller itself.
  The micro-controller runs a small program that periodically sends updates about its state to the host computer, and listens for commands from the computer, for example, to turn on and of a led. 
  
  @section{Getting Started}
  The DrFirmata library has only be used in conjunction with the Arduino platform so far.
  Therefore, the instructions to get started explain how to get the library up and running on an Arduino micro-controller.
  Getting the library to work for other micro-controllers should be analogous. 
  
  The easiest way to get started with DrFirmata is to download and install the software and the drivers that come with Arduino.
  Next, it is necessary to reprogram your Arduino micro-controller with the Firmata firmware.
  Firmata is included in the standard distribution of Arduino since version 12.
  In order to flash your Arduino with the Firmata firmware select the firmata program from the example sketches that come with the Arduino software.
  It can be found by selecting the following menu: File -> Examples -> Firmata -> StandardFirmata.
  Plug in your micro-controller board, and press the button upload from the Arduino software.
  Once you have installed Firmata on your Arduino, it is ready for DrFirmata.
  
  @section{Opening and Closing}
  We now show the functions for opening and closing the communication medium with the micro-controller.
  Communication with the micro-controller happens over the serial port.  
  It is very important to open the serial port before applying any other functionality from the library. 

  @defproc[ (open-firmata (string? path)) (void) ]{                             
  This function opens the serial port for communicating with the microntroller.
  It has to be called before any other function of the module.
  The path varibale depends on each board, it can be found either by making use of the command line or the arduino software.
  The following piece of code shows how to load the library and open the communication with the micro-controller. 

  
  @interaction[(require "firmata.rkt")
               (open-firmata "/dev/cu.usbserial-A5002tPQ")]  
                                           
  }
  @defproc[ (close-firmata) (bool?) ]{ 
  This function closes the serial port for communicating with the micro-controller.
  It also stops the module from reading from the serial port.
  While not strictly necessary, it is considered good coding practice to close the serial port when finished.
  }
  
  @section{Setting the Mode of a Pin}
  Many pins of a micro-controller have multiple purposes.
  The modes supported by the firmata firmware are INPUT_MODE, OUTPUT_MODE, ANALOG_MODE, PWM_MODE, SERVO_MODE.
  Before using a pin for a certain functionality, it is necessary to configure it as follows.
  
  @defproc[ (set-pin-mode! (number? port) (number? mode) ) (void) ]{ 
   @examples[
                                           (set-pin-mode! 5 INPUT_MODE)
                                                                       ]
                                 }
  

  @section{Registering for Updates}
  Once a connection with the micro-controller is established, it is possible to inform the micro-controller what kind of updates he needs to send to the host computer.
  You can register for updates on both analog and digital pins.
  Updates for analog pins can be controlled at the pin level by turning on its notification mechanism.
  Updates for digitial pins are controlled by turning on the notification mechanism of the port where they are attached to. 
  
  
  @defproc[ (report-analog-pin! (int? pin) (int? mode) ) (void) ]{ 
   Turns on or off the notification mechanism that periodically send updates about the given analog pin. 
   Controlling that you turn the notification mechanism on or off is done by passing the constant ON or OFF as the mode arrgument. 
                                                     }
  @defproc[ (report-digital-port! (int? port) (int? mode) ) () ]{ 
    Turns on or off the notification mechanism that sends updates about the given digital port when a change is detected.
    Controlling that you turn the notification mechanism on or off is done by passing the constant ON or OFF as the mode arrgument. 
  }

  @section{Reading and Writing Pins}
  Only when a pin is set for input, its value can be read.
  It is very important to realize that the most recent updated value will be returned.
  Note also that if you do not register for updates for an input pin, its values are not updated. 

  @defproc[ (is-pin-set? (int? port) (int? pin) ) (bool?) ]{
  Returns the most recent value of the digital pin on a certain port.
  In order to reflect changes for digital pins, you need to configure the pin as INPUT_MODE and to register for updates on the port. 
                                                            }
  @defproc[ (read-analog-pin (int? pin)) (int?) ]{
  Returns the most recent value of a analog pin.
  In order to reflect changes of the analog pin, you need to configure the pin in ANALOG_MODE and register for analog updates on the pin. 
  }
  
  Analogously, only when a pin is set for output, its valued can be changed. 

  @defproc[ (set-pin! (int? port) (int? pin)) (void) ]{ 
  Changes the value of a pin to high on the given port.
  The pin must be configured to operate in OUTPUT_MODE.
                                                       }
  @defproc[ (clear-pin! (int? port) (int? pin)) (void) ]{
  Changes the value of a pin to low on the given port.
  The pin must be configured to operate in OUTPUT_MODE.                                                       
                                                         }
  
  @section{Arduino Specific Functions}
  The Firmata protocol divides all the pins of your micro-controller into ports of eight pins.
  However, Arduino boards number the pins from 0 till 13.
  The following functions can be used in order to set and clear pins while using the numbers of the pins as indicated on the Arduino board.  
  
  @defproc[ (set-arduino-pin! (int? pin)) (void) ]{
  Sets the value of a certain pin to high as indicated on the Arduino board to high.
  The pin has to be configured to be in the OUTPUT_MODE.
                                                   }
  @defproc[ (clear-arduino-pin! (int? pin)) (void) ]{ 
    Sets the value of a certain pin to low as indicated on the Arduino board to high.
  The pin has to be configured to be in the OUTPUT_MODE. 
  }
  
  @section{Miscellaneous}
  The Firmata protocol has support to retrieve the current version of the firmware.
  The following functions implement such a functionality.
  @defproc[ (request-version) (void) ]{
  Sends an asynchronous message to the micro-controller in order to retrieve the current version number.                                      
                                       }
  @defproc[ (get-version) (string?) ]{ 
  Retrieves the latest version number that has been sent by the micro-controller.
  When request version has not been applied the current version is null. 
                                      }