MicroBitPin.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 #ifndef MICROBIT_PIN_H
00027 #define MICROBIT_PIN_H
00028 
00029 #include "mbed.h"
00030 #include "MicroBitConfig.h"
00031 #include "MicroBitComponent.h"
00032                                                         // Status Field flags...
00033 #define IO_STATUS_DIGITAL_IN                0x01        // Pin is configured as a digital input, with no pull up.
00034 #define IO_STATUS_DIGITAL_OUT               0x02        // Pin is configured as a digital output
00035 #define IO_STATUS_ANALOG_IN                 0x04        // Pin is Analog in
00036 #define IO_STATUS_ANALOG_OUT                0x08        // Pin is Analog out
00037 #define IO_STATUS_TOUCH_IN                  0x10        // Pin is a makey-makey style touch sensor
00038 #define IO_STATUS_EVENT_ON_EDGE             0x20        // Pin will generate events on pin change
00039 #define IO_STATUS_EVENT_PULSE_ON_EDGE       0x40        // Pin will generate events on pin change
00040 
00041 //#defines for each edge connector pin
00042 #define MICROBIT_PIN_P0                     P0_3        //P0 is the left most pad (ANALOG/DIGITAL) used to be P0_3 on green board
00043 #define MICROBIT_PIN_P1                     P0_2        //P1 is the middle pad (ANALOG/DIGITAL)
00044 #define MICROBIT_PIN_P2                     P0_1        //P2 is the right most pad (ANALOG/DIGITAL) used to be P0_1 on green board
00045 #define MICROBIT_PIN_P3                     P0_4        //COL1 (ANALOG/DIGITAL)
00046 #define MICROBIT_PIN_P4                     P0_5        //COL2 (ANALOG/DIGITAL)
00047 #define MICROBIT_PIN_P5                     P0_17       //BTN_A
00048 #define MICROBIT_PIN_P6                     P0_12       //COL9
00049 #define MICROBIT_PIN_P7                     P0_11       //COL8
00050 #define MICROBIT_PIN_P8                     P0_18       //PIN 18
00051 #define MICROBIT_PIN_P9                     P0_10       //COL7
00052 #define MICROBIT_PIN_P10                    P0_6        //COL3 (ANALOG/DIGITAL)
00053 #define MICROBIT_PIN_P11                    P0_26       //BTN_B
00054 #define MICROBIT_PIN_P12                    P0_20       //PIN 20
00055 #define MICROBIT_PIN_P13                    P0_23       //SCK
00056 #define MICROBIT_PIN_P14                    P0_22       //MISO
00057 #define MICROBIT_PIN_P15                    P0_21       //MOSI
00058 #define MICROBIT_PIN_P16                    P0_16       //PIN 16
00059 #define MICROBIT_PIN_P19                    P0_0        //SCL
00060 #define MICROBIT_PIN_P20                    P0_30       //SDA
00061 
00062 #define MICROBIT_PIN_MAX_OUTPUT             1023
00063 
00064 #define MICROBIT_PIN_MAX_SERVO_RANGE        180
00065 #define MICROBIT_PIN_DEFAULT_SERVO_RANGE    2000
00066 #define MICROBIT_PIN_DEFAULT_SERVO_CENTER   1500
00067 
00068 #define MICROBIT_PIN_EVENT_NONE             0
00069 #define MICROBIT_PIN_EVENT_ON_EDGE          1
00070 #define MICROBIT_PIN_EVENT_ON_PULSE         2
00071 #define MICROBIT_PIN_EVENT_ON_TOUCH         3
00072 
00073 #define MICROBIT_PIN_EVT_RISE               2
00074 #define MICROBIT_PIN_EVT_FALL               3
00075 #define MICROBIT_PIN_EVT_PULSE_HI           4
00076 #define MICROBIT_PIN_EVT_PULSE_LO           5
00077 
00078 /**
00079   * Pin capabilities enum.
00080   * Used to determine the capabilities of each Pin as some can only be digital, or can be both digital and analogue.
00081   */
00082 enum PinCapability{
00083     PIN_CAPABILITY_DIGITAL = 0x01,
00084     PIN_CAPABILITY_ANALOG = 0x02,
00085     PIN_CAPABILITY_AD = PIN_CAPABILITY_DIGITAL | PIN_CAPABILITY_ANALOG,
00086     PIN_CAPABILITY_ALL = PIN_CAPABILITY_DIGITAL | PIN_CAPABILITY_ANALOG
00087 };
00088 
00089 /**
00090   * Class definition for MicroBitPin.
00091   *
00092   * Commonly represents an I/O pin on the edge connector.
00093   */
00094 class MicroBitPin : public MicroBitComponent
00095 {
00096     // The mbed object looking after this pin at any point in time (untyped due to dynamic behaviour).
00097     void *pin;
00098     PinCapability capability;
00099     uint8_t pullMode;
00100 
00101     /**
00102       * Disconnect any attached mBed IO from this pin.
00103       *
00104       * Used only when pin changes mode (i.e. Input/Output/Analog/Digital)
00105       */
00106     void disconnect();
00107 
00108     /**
00109       * Performs a check to ensure that the current Pin is in control of a
00110       * DynamicPwm instance, and if it's not, allocates a new DynamicPwm instance.
00111       */
00112     int obtainAnalogChannel();
00113 
00114     /**
00115       * Interrupt handler for when an rise interrupt is triggered.
00116       */
00117     void onRise();
00118 
00119     /**
00120       * Interrupt handler for when an fall interrupt is triggered.
00121       */
00122     void onFall();
00123 
00124     /**
00125       * This member function manages the calculation of the timestamp of a pulse detected
00126       * on a pin whilst in IO_STATUS_EVENT_PULSE_ON_EDGE or IO_STATUS_EVENT_ON_EDGE modes.
00127       *
00128       * @param eventValue the event value to distribute onto the message bus.
00129       */
00130     void pulseWidthEvent(int eventValue);
00131 
00132     /**
00133       * This member function will construct an TimedInterruptIn instance, and configure
00134       * interrupts for rise and fall.
00135       *
00136       * @param eventType the specific mode used in interrupt context to determine how an
00137       *                  edge/rise is processed.
00138       *
00139       * @return MICROBIT_OK on success
00140       */
00141     int enableRiseFallEvents(int eventType);
00142 
00143     /**
00144       * If this pin is in a mode where the pin is generating events, it will destruct
00145       * the current instance attached to this MicroBitPin instance.
00146       *
00147       * @return MICROBIT_OK on success.
00148       */
00149     int disableEvents();
00150 
00151     public:
00152 
00153     // mbed PinName of this pin.
00154     PinName name;
00155 
00156     /**
00157       * Constructor.
00158       * Create a MicroBitPin instance, generally used to represent a pin on the edge connector.
00159       *
00160       * @param id the unique EventModel id of this component.
00161       *
00162       * @param name the mbed PinName for this MicroBitPin instance.
00163       *
00164       * @param capability the capabilities this MicroBitPin instance should have.
00165       *                   (PIN_CAPABILITY_DIGITAL, PIN_CAPABILITY_ANALOG, PIN_CAPABILITY_AD, PIN_CAPABILITY_ALL)
00166       *
00167       * @code
00168       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_ALL);
00169       * @endcode
00170       */
00171     MicroBitPin(int id, PinName name, PinCapability capability);
00172 
00173     /**
00174       * Configures this IO pin as a digital output (if necessary) and sets the pin to 'value'.
00175       *
00176       * @param value 0 (LO) or 1 (HI)
00177       *
00178       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00179       *         if the given pin does not have digital capability.
00180       *
00181       * @code
00182       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00183       * P0.setDigitalValue(1); // P0 is now HI
00184       * @endcode
00185       */
00186     int setDigitalValue(int value);
00187 
00188     /**
00189       * Configures this IO pin as a digital input (if necessary) and tests its current value.
00190       *
00191       *
00192       * @return 1 if this input is high, 0 if input is LO, or MICROBIT_NOT_SUPPORTED
00193       *         if the given pin does not have digital capability.
00194       *
00195       * @code
00196       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00197       * P0.getDigitalValue(); // P0 is either 0 or 1;
00198       * @endcode
00199       */
00200     int getDigitalValue();
00201 
00202     /**
00203       * Configures this IO pin as a digital input with the specified internal pull-up/pull-down configuraiton (if necessary) and tests its current value.
00204       *
00205       * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone
00206       *
00207       * @return 1 if this input is high, 0 if input is LO, or MICROBIT_NOT_SUPPORTED
00208       *         if the given pin does not have digital capability.
00209       *
00210       * @code
00211       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00212       * P0.getDigitalValue(PullUp); // P0 is either 0 or 1;
00213       * @endcode
00214       */
00215     int getDigitalValue(PinMode pull);
00216 
00217     /**
00218       * Configures this IO pin as an analog/pwm output, and change the output value to the given level.
00219       *
00220       * @param value the level to set on the output pin, in the range 0 - 1024
00221       *
00222       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00223       *         if the given pin does not have analog capability.
00224       */
00225     int setAnalogValue(int value);
00226 
00227     /**
00228       * Configures this IO pin as an analog/pwm output (if necessary) and configures the period to be 20ms,
00229       * with a duty cycle between 500 us and 2500 us.
00230       *
00231       * A value of 180 sets the duty cycle to be 2500us, and a value of 0 sets the duty cycle to be 500us by default.
00232       *
00233       * This range can be modified to fine tune, and also tolerate different servos.
00234       *
00235       * @param value the level to set on the output pin, in the range 0 - 180.
00236       *
00237       * @param range which gives the span of possible values the i.e. the lower and upper bounds (center +/- range/2). Defaults to MICROBIT_PIN_DEFAULT_SERVO_RANGE.
00238       *
00239       * @param center the center point from which to calculate the lower and upper bounds. Defaults to MICROBIT_PIN_DEFAULT_SERVO_CENTER
00240       *
00241       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00242       *         if the given pin does not have analog capability.
00243       */
00244     int setServoValue(int value, int range = MICROBIT_PIN_DEFAULT_SERVO_RANGE, int center = MICROBIT_PIN_DEFAULT_SERVO_CENTER);
00245 
00246     /**
00247       * Configures this IO pin as an analogue input (if necessary), and samples the Pin for its analog value.
00248       *
00249       * @return the current analogue level on the pin, in the range 0 - 1024, or
00250       *         MICROBIT_NOT_SUPPORTED if the given pin does not have analog capability.
00251       *
00252       * @code
00253       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00254       * P0.getAnalogValue(); // P0 is a value in the range of 0 - 1024
00255       * @endcode
00256       */
00257     int getAnalogValue();
00258 
00259     /**
00260       * Determines if this IO pin is currently configured as an input.
00261       *
00262       * @return 1 if pin is an analog or digital input, 0 otherwise.
00263       */
00264     int isInput();
00265 
00266     /**
00267       * Determines if this IO pin is currently configured as an output.
00268       *
00269       * @return 1 if pin is an analog or digital output, 0 otherwise.
00270       */
00271     int isOutput();
00272 
00273     /**
00274       * Determines if this IO pin is currently configured for digital use.
00275       *
00276       * @return 1 if pin is digital, 0 otherwise.
00277       */
00278     int isDigital();
00279 
00280     /**
00281       * Determines if this IO pin is currently configured for analog use.
00282       *
00283       * @return 1 if pin is analog, 0 otherwise.
00284       */
00285     int isAnalog();
00286 
00287     /**
00288       * Configures this IO pin as a "makey makey" style touch sensor (if necessary)
00289       * and tests its current debounced state.
00290       *
00291       * Users can also subscribe to MicroBitButton events generated from this pin.
00292       *
00293       * @return 1 if pin is touched, 0 if not, or MICROBIT_NOT_SUPPORTED if this pin does not support touch capability.
00294       *
00295       * @code
00296       * MicroBitMessageBus bus;
00297       *
00298       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_ALL);
00299       * if(P0.isTouched())
00300       * {
00301       *     //do something!
00302       * }
00303       *
00304       * // subscribe to events generated by this pin!
00305       * bus.listen(MICROBIT_ID_IO_P0, MICROBIT_BUTTON_EVT_CLICK, someFunction);
00306       * @endcode
00307       */
00308     int isTouched();
00309 
00310     /**
00311       * Configures this IO pin as an analog/pwm output if it isn't already, configures the period to be 20ms,
00312       * and sets the pulse width, based on the value it is given.
00313       *
00314       * @param pulseWidth the desired pulse width in microseconds.
00315       *
00316       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00317       *         if the given pin does not have analog capability.
00318       */
00319     int setServoPulseUs(int pulseWidth);
00320 
00321     /**
00322       * Configures the PWM period of the analog output to the given value.
00323       *
00324       * @param period The new period for the analog output in milliseconds.
00325       *
00326       * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the
00327       *         given pin is not configured as an analog output.
00328       */
00329     int setAnalogPeriod(int period);
00330 
00331     /**
00332       * Configures the PWM period of the analog output to the given value.
00333       *
00334       * @param period The new period for the analog output in microseconds.
00335       *
00336       * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the
00337       *         given pin is not configured as an analog output.
00338       */
00339     int setAnalogPeriodUs(int period);
00340 
00341     /**
00342       * Obtains the PWM period of the analog output in microseconds.
00343       *
00344       * @return the period on success, or MICROBIT_NOT_SUPPORTED if the
00345       *         given pin is not configured as an analog output.
00346       */
00347     int getAnalogPeriodUs();
00348 
00349     /**
00350       * Obtains the PWM period of the analog output in milliseconds.
00351       *
00352       * @return the period on success, or MICROBIT_NOT_SUPPORTED if the
00353       *         given pin is not configured as an analog output.
00354       */
00355     int getAnalogPeriod();
00356 
00357     /**
00358       * Configures the pull of this pin.
00359       *
00360       * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone
00361       *
00362       * @return MICROBIT_NOT_SUPPORTED if the current pin configuration is anything other
00363       *         than a digital input, otherwise MICROBIT_OK.
00364       */
00365     int setPull(PinMode pull);
00366 
00367     /**
00368       * Configures the events generated by this MicroBitPin instance.
00369       *
00370       * MICROBIT_PIN_EVENT_ON_EDGE - Configures this pin to a digital input, and generates events whenever a rise/fall is detected on this pin. (MICROBIT_PIN_EVT_RISE, MICROBIT_PIN_EVT_FALL)
00371       * MICROBIT_PIN_EVENT_ON_PULSE - Configures this pin to a digital input, and generates events where the timestamp is the duration that this pin was either HI or LO. (MICROBIT_PIN_EVT_PULSE_HI, MICROBIT_PIN_EVT_PULSE_LO)
00372       * MICROBIT_PIN_EVENT_ON_TOUCH - Configures this pin as a makey makey style touch sensor, in the form of a MicroBitButton. Normal button events will be generated using the ID of this pin.
00373       * MICROBIT_PIN_EVENT_NONE - Disables events for this pin.
00374       *
00375       * @param eventType One of: MICROBIT_PIN_EVENT_ON_EDGE, MICROBIT_PIN_EVENT_ON_PULSE, MICROBIT_PIN_EVENT_ON_TOUCH, MICROBIT_PIN_EVENT_NONE
00376       *
00377       * @code
00378       * MicroBitMessageBus bus;
00379       *
00380       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00381       * P0.eventOn(MICROBIT_PIN_EVENT_ON_PULSE);
00382       *
00383       * void onPulse(MicroBitEvent evt)
00384       * {
00385       *     int duration = evt.timestamp;
00386       * }
00387       *
00388       * bus.listen(MICROBIT_ID_IO_P0, MICROBIT_PIN_EVT_PULSE_HI, onPulse, MESSAGE_BUS_LISTENER_IMMEDIATE)
00389       * @endcode
00390       *
00391       * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the given eventype does not match
00392       *
00393       * @note In the MICROBIT_PIN_EVENT_ON_PULSE mode, the smallest pulse that was reliably detected was 85us, around 5khz. If more precision is required,
00394       *       please use the InterruptIn class supplied by ARM mbed.
00395       */
00396     int eventOn(int eventType);
00397 };
00398 
00399 #endif