Arduino/libraries/Firmata/Firmata.h

   1 /*
   2   Firmata.h - Firmata library v2.5.7 - 2017-08-19
   3   Copyright (c) 2006-2008 Hans-Christoph Steiner.  All rights reserved.
   4   Copyright (C) 2009-2017 Jeff Hoefs.  All rights reserved.
   5
   6   This library is free software; you can redistribute it and/or
   7   modify it under the terms of the GNU Lesser General Public
   8   License as published by the Free Software Foundation; either
   9   version 2.1 of the License, or (at your option) any later version.
  10
  11   See file LICENSE.txt for further informations on licensing terms.
  12 */
  13
  14 #ifndef Firmata_h
  15 #define Firmata_h
  16
  17 #include "Boards.h"  /* Hardware Abstraction Layer + Wiring/Arduino */
  18 #include "FirmataDefines.h"
  19 #include "FirmataMarshaller.h"
  20 #include "FirmataParser.h"
  21
  22 /* DEPRECATED as of Firmata v2.5.1. As of 2.5.1 there are separate version numbers for
  23  * the protocol version and the firmware version.
  24  */
  25 #define FIRMATA_MAJOR_VERSION           2 // same as FIRMATA_PROTOCOL_MAJOR_VERSION
  26 #define FIRMATA_MINOR_VERSION           5 // same as FIRMATA_PROTOCOL_MINOR_VERSION
  27 #define FIRMATA_BUGFIX_VERSION          1 // same as FIRMATA_PROTOCOL_BUGFIX_VERSION
  28
  29 // extended command set using sysex (0-127/0x00-0x7F)
  30 /* 0x00-0x0F reserved for user-defined commands */
  31 // these are DEPRECATED to make the naming more consistent
  32 #define FIRMATA_STRING          0x71 // same as STRING_DATA
  33 #define SYSEX_I2C_REQUEST       0x76 // same as I2C_REQUEST
  34 #define SYSEX_I2C_REPLY         0x77 // same as I2C_REPLY
  35 #define SYSEX_SAMPLING_INTERVAL 0x7A // same as SAMPLING_INTERVAL
  36
  37 // pin modes
  38 //#define INPUT                 0x00 // defined in Arduino.h
  39 //#define OUTPUT                0x01 // defined in Arduino.h
  40 // DEPRECATED as of Firmata v2.5
  41 #define ANALOG                  0x02 // same as PIN_MODE_ANALOG
  42 #define PWM                     0x03 // same as PIN_MODE_PWM
  43 #define SERVO                   0x04 // same as PIN_MODE_SERVO
  44 #define SHIFT                   0x05 // same as PIN_MODE_SHIFT
  45 #define I2C                     0x06 // same as PIN_MODE_I2C
  46 #define ONEWIRE                 0x07 // same as PIN_MODE_ONEWIRE
  47 #define STEPPER                 0x08 // same as PIN_MODE_STEPPER
  48 #define ENCODER                 0x09 // same as PIN_MODE_ENCODER
  49 #define IGNORE                  0x7F // same as PIN_MODE_IGNORE
  50
  51 namespace firmata {
  52
  53 // TODO make it a subclass of a generic Serial/Stream base class
  54 class FirmataClass
  55 {
  56   public:
  57     typedef void (*callbackFunction)(uint8_t, int);
  58     typedef void (*systemCallbackFunction)(void);
  59     typedef void (*stringCallbackFunction)(char *);
  60     typedef void (*sysexCallbackFunction)(uint8_t command, uint8_t argc, uint8_t *argv);
  61
  62     FirmataClass();
  63
  64     /* Arduino constructors */
  65     void begin();
  66     void begin(long);
  67     void begin(Stream &s);
  68
  69     /* querying functions */
  70     void printVersion(void);
  71     void blinkVersion(void);
  72     void printFirmwareVersion(void);
  73
  74     //void setFirmwareVersion(byte major, byte minor);  // see macro below
  75     void setFirmwareNameAndVersion(const char *name, byte major, byte minor);
  76     void disableBlinkVersion();
  77
  78     /* serial receive handling */
  79     int available(void);
  80     void processInput(void);
  81     void parse(unsigned char value);
  82     boolean isParsingMessage(void);
  83
  84     /* serial send handling */
  85     void sendAnalog(byte pin, int value);
  86     void sendDigital(byte pin, int value); // TODO implement this
  87     void sendDigitalPort(byte portNumber, int portData);
  88     void sendString(const char *string);
  89     void sendString(byte command, const char *string);
  90     void sendSysex(byte command, byte bytec, byte *bytev);
  91     void write(byte c);
  92
  93     /* attach & detach callback functions to messages */
  94     void attach(uint8_t command, callbackFunction newFunction);
  95     void attach(uint8_t command, systemCallbackFunction newFunction);
  96     void attach(uint8_t command, stringCallbackFunction newFunction);
  97     void attach(uint8_t command, sysexCallbackFunction newFunction);
  98     void detach(uint8_t command);
  99
 100     /* access pin state and config */
 101     byte getPinMode(byte pin);
 102     void setPinMode(byte pin, byte config);
 103
 104     /* access pin state */
 105     int getPinState(byte pin);
 106     void setPinState(byte pin, int state);
 107
 108     /* utility methods */
 109     void sendValueAsTwo7bitBytes(int value);
 110     void startSysex(void);
 111     void endSysex(void);
 112
 113   private:
 114     uint8_t parserBuffer[MAX_DATA_BYTES];
 115     FirmataMarshaller marshaller;
 116     FirmataParser parser;
 117     Stream *FirmataStream;
 118
 119     /* firmware name and version */
 120     byte firmwareVersionCount;
 121     byte *firmwareVersionVector;
 122
 123     /* pin configuration */
 124     byte pinConfig[TOTAL_PINS];
 125     int pinState[TOTAL_PINS];
 126
 127     boolean blinkVersionDisabled;
 128
 129     /* private methods ------------------------------ */
 130     void strobeBlinkPin(byte pin, int count, int onInterval, int offInterval);
 131     friend void FirmataMarshaller::encodeByteStream (size_t bytec, uint8_t * bytev, size_t max_bytes = 0) const;
 132
 133     /* callback functions */
 134     static callbackFunction currentAnalogCallback;
 135     static callbackFunction currentDigitalCallback;
 136     static callbackFunction currentPinModeCallback;
 137     static callbackFunction currentPinValueCallback;
 138     static callbackFunction currentReportAnalogCallback;
 139     static callbackFunction currentReportDigitalCallback;
 140     static stringCallbackFunction currentStringCallback;
 141     static sysexCallbackFunction currentSysexCallback;
 142     static systemCallbackFunction currentSystemResetCallback;
 143
 144     /* static callbacks */
 145     inline static void staticAnalogCallback (void *, uint8_t command, uint16_t value) { if ( currentAnalogCallback ) { currentAnalogCallback(command,(int)value); } }
 146     inline static void staticDigitalCallback (void *, uint8_t command, uint16_t value) { if ( currentDigitalCallback ) { currentDigitalCallback(command, (int)value); } }
 147     inline static void staticPinModeCallback (void *, uint8_t command, uint16_t value) { if ( currentPinModeCallback ) { currentPinModeCallback(command, (int)value); } }
 148     inline static void staticPinValueCallback (void *, uint8_t command, uint16_t value) { if ( currentPinValueCallback ) { currentPinValueCallback(command, (int)value); } }
 149     inline static void staticReportAnalogCallback (void *, uint8_t command, uint16_t value) { if ( currentReportAnalogCallback ) { currentReportAnalogCallback(command, (int)value); } }
 150     inline static void staticReportDigitalCallback (void *, uint8_t command, uint16_t value) { if ( currentReportDigitalCallback ) { currentReportDigitalCallback(command, (int)value); } }
 151     inline static void staticStringCallback (void *, const char * c_str) { if ( currentStringCallback ) { currentStringCallback((char *)c_str); } }
 152     inline static void staticSysexCallback (void *, uint8_t command, size_t argc, uint8_t *argv) { if ( currentSysexCallback ) { currentSysexCallback(command, (uint8_t)argc, argv); } }
 153     inline static void staticReportFirmwareCallback (void * context, size_t, size_t, const char *) { if ( context ) { ((FirmataClass *)context)->printFirmwareVersion(); } }
 154     inline static void staticReportVersionCallback (void * context) { if ( context ) { ((FirmataClass *)context)->printVersion(); } }
 155     inline static void staticSystemResetCallback (void *) { if ( currentSystemResetCallback ) { currentSystemResetCallback(); } }
 156 };
 157
 158 } // namespace firmata
 159
 160 extern "C" {
 161   // callback function types
 162   typedef firmata::FirmataClass::callbackFunction callbackFunction;
 163   typedef firmata::FirmataClass::systemCallbackFunction systemCallbackFunction;
 164   typedef firmata::FirmataClass::stringCallbackFunction stringCallbackFunction;
 165   typedef firmata::FirmataClass::sysexCallbackFunction sysexCallbackFunction;
 166 }
 167
 168 extern firmata::FirmataClass Firmata;
 169
 170 /*==============================================================================
 171  * MACROS
 172  *============================================================================*/
 173
 174 /* shortcut for setFirmwareNameAndVersion() that uses __FILE__ to set the
 175  * firmware name.  It needs to be a macro so that __FILE__ is included in the
 176  * firmware source file rather than the library source file.
 177  */
 178 #define setFirmwareVersion(x, y)   setFirmwareNameAndVersion(__FILE__, x, y)
 179
 180 #endif /* Firmata_h */