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_EVENTBUS_ENABLED          0x80        // Pin is will generate events on change
00039 
00040 //#defines for each edge connector pin
00041 #define MICROBIT_PIN_P0                     P0_3        //P0 is the left most pad (ANALOG/DIGITAL) used to be P0_3 on green board
00042 #define MICROBIT_PIN_P1                     P0_2        //P1 is the middle pad (ANALOG/DIGITAL)
00043 #define MICROBIT_PIN_P2                     P0_1        //P2 is the right most pad (ANALOG/DIGITAL) used to be P0_1 on green board
00044 #define MICROBIT_PIN_P3                     P0_4        //COL1 (ANALOG/DIGITAL)
00045 #define MICROBIT_PIN_P4                     P0_5        //COL2 (ANALOG/DIGITAL)
00046 #define MICROBIT_PIN_P5                     P0_17       //BTN_A
00047 #define MICROBIT_PIN_P6                     P0_12       //COL9
00048 #define MICROBIT_PIN_P7                     P0_11       //COL8
00049 #define MICROBIT_PIN_P8                     P0_18       //PIN 18
00050 #define MICROBIT_PIN_P9                     P0_10       //COL7
00051 #define MICROBIT_PIN_P10                    P0_6        //COL3 (ANALOG/DIGITAL)
00052 #define MICROBIT_PIN_P11                    P0_26       //BTN_B
00053 #define MICROBIT_PIN_P12                    P0_20       //PIN 20
00054 #define MICROBIT_PIN_P13                    P0_23       //SCK
00055 #define MICROBIT_PIN_P14                    P0_22       //MISO
00056 #define MICROBIT_PIN_P15                    P0_21       //MOSI
00057 #define MICROBIT_PIN_P16                    P0_16       //PIN 16
00058 #define MICROBIT_PIN_P19                    P0_0        //SCL
00059 #define MICROBIT_PIN_P20                    P0_30       //SDA
00060 
00061 #define MICROBIT_PIN_MAX_OUTPUT             1023
00062 
00063 #define MICROBIT_PIN_MAX_SERVO_RANGE        180
00064 #define MICROBIT_PIN_DEFAULT_SERVO_RANGE    2000
00065 #define MICROBIT_PIN_DEFAULT_SERVO_CENTER   1500
00066 
00067 
00068 /**
00069   * Pin capabilities enum.
00070   * Used to determine the capabilities of each Pin as some can only be digital, or can be both digital and analogue.
00071   */
00072 enum PinCapability{
00073     PIN_CAPABILITY_DIGITAL = 0x01,
00074     PIN_CAPABILITY_ANALOG = 0x02,
00075     PIN_CAPABILITY_TOUCH = 0x04,
00076     PIN_CAPABILITY_AD = PIN_CAPABILITY_DIGITAL | PIN_CAPABILITY_ANALOG,
00077     PIN_CAPABILITY_ALL = PIN_CAPABILITY_DIGITAL | PIN_CAPABILITY_ANALOG | PIN_CAPABILITY_TOUCH
00078 
00079 };
00080 
00081 /**
00082   * Class definition for MicroBitPin.
00083   *
00084   * Commonly represents an I/O pin on the edge connector.
00085   */
00086 class MicroBitPin : public MicroBitComponent
00087 {
00088     // The mbed object looking after this pin at any point in time (untyped due to dynamic behaviour).
00089     void *pin;
00090 
00091     PinCapability capability;
00092 
00093     /**
00094       * Disconnect any attached mBed IO from this pin.
00095       *
00096       * Used only when pin changes mode (i.e. Input/Output/Analog/Digital)
00097       */
00098     void disconnect();
00099 
00100     /**
00101       * Performs a check to ensure that the current Pin is in control of a
00102       * DynamicPwm instance, and if it's not, allocates a new DynamicPwm instance.
00103       */
00104     int obtainAnalogChannel();
00105 
00106     public:
00107 
00108     // mbed PinName of this pin.
00109     PinName name;
00110 
00111     /**
00112       * Constructor.
00113       * Create a MicroBitPin instance, generally used to represent a pin on the edge connector.
00114       *
00115       * @param id the unique EventModel id of this component.
00116       *
00117       * @param name the mbed PinName for this MicroBitPin instance.
00118       *
00119       * @param capability the capabilities this MicroBitPin instance should have.
00120       *                   (PIN_CAPABILITY_DIGITAL, PIN_CAPABILITY_ANALOG, PIN_CAPABILITY_TOUCH, PIN_CAPABILITY_AD, PIN_CAPABILITY_ALL)
00121       *
00122       * @code
00123       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_ALL);
00124       * @endcode
00125       */
00126     MicroBitPin(int id, PinName name, PinCapability capability);
00127 
00128     /**
00129       * Configures this IO pin as a digital output (if necessary) and sets the pin to 'value'.
00130       *
00131       * @param value 0 (LO) or 1 (HI)
00132       *
00133       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00134       *         if the given pin does not have digital capability.
00135       *
00136       * @code
00137       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00138       * P0.setDigitalValue(1); // P0 is now HI
00139       * @endcode
00140       */
00141     int setDigitalValue(int value);
00142 
00143     /**
00144       * Configures this IO pin as a digital input (if necessary) and tests its current value.
00145       *
00146       * @return 1 if this input is high, 0 if input is LO, or MICROBIT_NOT_SUPPORTED
00147       *         if the given pin does not have analog capability.
00148       *
00149       * @code
00150       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00151       * P0.getDigitalValue(); // P0 is either 0 or 1;
00152       * @endcode
00153       */
00154     int getDigitalValue();
00155 
00156     /**
00157       * Configures this IO pin as an analog/pwm output, and change the output value to the given level.
00158       *
00159       * @param value the level to set on the output pin, in the range 0 - 1024
00160       *
00161       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00162       *         if the given pin does not have analog capability.
00163       */
00164     int setAnalogValue(int value);
00165 
00166     /**
00167       * Configures this IO pin as an analog/pwm output (if necessary) and configures the period to be 20ms,
00168       * with a duty cycle between 500 us and 2500 us.
00169       *
00170       * 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.
00171       *
00172       * This range can be modified to fine tune, and also tolerate different servos.
00173       *
00174       * @param value the level to set on the output pin, in the range 0 - 180.
00175       *
00176       * @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.
00177       *
00178       * @param center the center point from which to calculate the lower and upper bounds. Defaults to MICROBIT_PIN_DEFAULT_SERVO_CENTER
00179       *
00180       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00181       *         if the given pin does not have analog capability.
00182       */
00183     int setServoValue(int value, int range = MICROBIT_PIN_DEFAULT_SERVO_RANGE, int center = MICROBIT_PIN_DEFAULT_SERVO_CENTER);
00184 
00185     /**
00186       * Configures this IO pin as an analogue input (if necessary), and samples the Pin for its analog value.
00187       *
00188       * @return the current analogue level on the pin, in the range 0 - 1024, or
00189       *         MICROBIT_NOT_SUPPORTED if the given pin does not have analog capability.
00190       *
00191       * @code
00192       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
00193       * P0.getAnalogValue(); // P0 is a value in the range of 0 - 1024
00194       * @endcode
00195       */
00196     int getAnalogValue();
00197 
00198     /**
00199       * Determines if this IO pin is currently configured as an input.
00200       *
00201       * @return 1 if pin is an analog or digital input, 0 otherwise.
00202       */
00203     int isInput();
00204 
00205     /**
00206       * Determines if this IO pin is currently configured as an output.
00207       *
00208       * @return 1 if pin is an analog or digital output, 0 otherwise.
00209       */
00210     int isOutput();
00211 
00212     /**
00213       * Determines if this IO pin is currently configured for digital use.
00214       *
00215       * @return 1 if pin is digital, 0 otherwise.
00216       */
00217     int isDigital();
00218 
00219     /**
00220       * Determines if this IO pin is currently configured for analog use.
00221       *
00222       * @return 1 if pin is analog, 0 otherwise.
00223       */
00224     int isAnalog();
00225 
00226     /**
00227       * Configures this IO pin as a "makey makey" style touch sensor (if necessary)
00228       * and tests its current debounced state.
00229       *
00230       * Users can also subscribe to MicroBitButton events generated from this pin.
00231       *
00232       * @return 1 if pin is touched, 0 if not, or MICROBIT_NOT_SUPPORTED if this pin does not support touch capability.
00233       *
00234       * @code
00235       * MicroBitMessageBus bus;
00236       *
00237       * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_ALL);
00238       * if(P0.isTouched())
00239       * {
00240       *     //do something!
00241       * }
00242       *
00243       * // subscribe to events generated by this pin!
00244       * bus.listen(MICROBIT_ID_IO_P0, MICROBIT_BUTTON_EVT_CLICK, someFunction);
00245       * @endcode
00246       */
00247     int isTouched();
00248 
00249     /**
00250       * Configures this IO pin as an analog/pwm output if it isn't already, configures the period to be 20ms,
00251       * and sets the pulse width, based on the value it is given.
00252       *
00253       * @param pulseWidth the desired pulse width in microseconds.
00254       *
00255       * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
00256       *         if the given pin does not have analog capability.
00257       */
00258     int setServoPulseUs(int pulseWidth);
00259 
00260     /**
00261       * Configures the PWM period of the analog output to the given value.
00262       *
00263       * @param period The new period for the analog output in milliseconds.
00264       *
00265       * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the
00266       *         given pin is not configured as an analog output.
00267       */
00268     int setAnalogPeriod(int period);
00269 
00270     /**
00271       * Configures the PWM period of the analog output to the given value.
00272       *
00273       * @param period The new period for the analog output in microseconds.
00274       *
00275       * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the
00276       *         given pin is not configured as an analog output.
00277       */
00278     int setAnalogPeriodUs(int period);
00279 
00280     /**
00281       * Obtains the PWM period of the analog output in microseconds.
00282       *
00283       * @return the period on success, or MICROBIT_NOT_SUPPORTED if the
00284       *         given pin is not configured as an analog output.
00285       */
00286     int getAnalogPeriodUs();
00287 
00288     /**
00289       * Obtains the PWM period of the analog output in milliseconds.
00290       *
00291       * @return the period on success, or MICROBIT_NOT_SUPPORTED if the
00292       *         given pin is not configured as an analog output.
00293       */
00294     int getAnalogPeriod();
00295 };
00296 
00297 #endif