Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/inc/drivers/MicroBitPin.h@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MrBedfordVan 0:b9164b348919 1 /*
MrBedfordVan 0:b9164b348919 2 The MIT License (MIT)
MrBedfordVan 0:b9164b348919 3
MrBedfordVan 0:b9164b348919 4 Copyright (c) 2016 British Broadcasting Corporation.
MrBedfordVan 0:b9164b348919 5 This software is provided by Lancaster University by arrangement with the BBC.
MrBedfordVan 0:b9164b348919 6
MrBedfordVan 0:b9164b348919 7 Permission is hereby granted, free of charge, to any person obtaining a
MrBedfordVan 0:b9164b348919 8 copy of this software and associated documentation files (the "Software"),
MrBedfordVan 0:b9164b348919 9 to deal in the Software without restriction, including without limitation
MrBedfordVan 0:b9164b348919 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
MrBedfordVan 0:b9164b348919 11 and/or sell copies of the Software, and to permit persons to whom the
MrBedfordVan 0:b9164b348919 12 Software is furnished to do so, subject to the following conditions:
MrBedfordVan 0:b9164b348919 13
MrBedfordVan 0:b9164b348919 14 The above copyright notice and this permission notice shall be included in
MrBedfordVan 0:b9164b348919 15 all copies or substantial portions of the Software.
MrBedfordVan 0:b9164b348919 16
MrBedfordVan 0:b9164b348919 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
MrBedfordVan 0:b9164b348919 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
MrBedfordVan 0:b9164b348919 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
MrBedfordVan 0:b9164b348919 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
MrBedfordVan 0:b9164b348919 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
MrBedfordVan 0:b9164b348919 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
MrBedfordVan 0:b9164b348919 23 DEALINGS IN THE SOFTWARE.
MrBedfordVan 0:b9164b348919 24 */
MrBedfordVan 0:b9164b348919 25
MrBedfordVan 0:b9164b348919 26 #ifndef MICROBIT_PIN_H
MrBedfordVan 0:b9164b348919 27 #define MICROBIT_PIN_H
MrBedfordVan 0:b9164b348919 28
MrBedfordVan 0:b9164b348919 29 #include "mbed.h"
MrBedfordVan 0:b9164b348919 30 #include "MicroBitConfig.h"
MrBedfordVan 0:b9164b348919 31 #include "MicroBitComponent.h"
MrBedfordVan 0:b9164b348919 32 // Status Field flags...
MrBedfordVan 0:b9164b348919 33 #define IO_STATUS_DIGITAL_IN 0x01 // Pin is configured as a digital input, with no pull up.
MrBedfordVan 0:b9164b348919 34 #define IO_STATUS_DIGITAL_OUT 0x02 // Pin is configured as a digital output
MrBedfordVan 0:b9164b348919 35 #define IO_STATUS_ANALOG_IN 0x04 // Pin is Analog in
MrBedfordVan 0:b9164b348919 36 #define IO_STATUS_ANALOG_OUT 0x08 // Pin is Analog out
MrBedfordVan 0:b9164b348919 37 #define IO_STATUS_TOUCH_IN 0x10 // Pin is a makey-makey style touch sensor
MrBedfordVan 0:b9164b348919 38 #define IO_STATUS_EVENT_ON_EDGE 0x20 // Pin will generate events on pin change
MrBedfordVan 0:b9164b348919 39 #define IO_STATUS_EVENT_PULSE_ON_EDGE 0x40 // Pin will generate events on pin change
MrBedfordVan 0:b9164b348919 40
MrBedfordVan 0:b9164b348919 41 //#defines for each edge connector pin
MrBedfordVan 0:b9164b348919 42 #define MICROBIT_PIN_P0 P0_3 //P0 is the left most pad (ANALOG/DIGITAL) used to be P0_3 on green board
MrBedfordVan 0:b9164b348919 43 #define MICROBIT_PIN_P1 P0_2 //P1 is the middle pad (ANALOG/DIGITAL)
MrBedfordVan 0:b9164b348919 44 #define MICROBIT_PIN_P2 P0_1 //P2 is the right most pad (ANALOG/DIGITAL) used to be P0_1 on green board
MrBedfordVan 0:b9164b348919 45 #define MICROBIT_PIN_P3 P0_4 //COL1 (ANALOG/DIGITAL)
MrBedfordVan 0:b9164b348919 46 #define MICROBIT_PIN_P4 P0_5 //COL2 (ANALOG/DIGITAL)
MrBedfordVan 0:b9164b348919 47 #define MICROBIT_PIN_P5 P0_17 //BTN_A
MrBedfordVan 0:b9164b348919 48 #define MICROBIT_PIN_P6 P0_12 //COL9
MrBedfordVan 0:b9164b348919 49 #define MICROBIT_PIN_P7 P0_11 //COL8
MrBedfordVan 0:b9164b348919 50 #define MICROBIT_PIN_P8 P0_18 //PIN 18
MrBedfordVan 0:b9164b348919 51 #define MICROBIT_PIN_P9 P0_10 //COL7
MrBedfordVan 0:b9164b348919 52 #define MICROBIT_PIN_P10 P0_6 //COL3 (ANALOG/DIGITAL)
MrBedfordVan 0:b9164b348919 53 #define MICROBIT_PIN_P11 P0_26 //BTN_B
MrBedfordVan 0:b9164b348919 54 #define MICROBIT_PIN_P12 P0_20 //PIN 20
MrBedfordVan 0:b9164b348919 55 #define MICROBIT_PIN_P13 P0_23 //SCK
MrBedfordVan 0:b9164b348919 56 #define MICROBIT_PIN_P14 P0_22 //MISO
MrBedfordVan 0:b9164b348919 57 #define MICROBIT_PIN_P15 P0_21 //MOSI
MrBedfordVan 0:b9164b348919 58 #define MICROBIT_PIN_P16 P0_16 //PIN 16
MrBedfordVan 0:b9164b348919 59 #define MICROBIT_PIN_P19 P0_0 //SCL
MrBedfordVan 0:b9164b348919 60 #define MICROBIT_PIN_P20 P0_30 //SDA
MrBedfordVan 0:b9164b348919 61
MrBedfordVan 0:b9164b348919 62 #define MICROBIT_PIN_MAX_OUTPUT 1023
MrBedfordVan 0:b9164b348919 63
MrBedfordVan 0:b9164b348919 64 #define MICROBIT_PIN_MAX_SERVO_RANGE 180
MrBedfordVan 0:b9164b348919 65 #define MICROBIT_PIN_DEFAULT_SERVO_RANGE 2000
MrBedfordVan 0:b9164b348919 66 #define MICROBIT_PIN_DEFAULT_SERVO_CENTER 1500
MrBedfordVan 0:b9164b348919 67
MrBedfordVan 0:b9164b348919 68 #define MICROBIT_PIN_EVENT_NONE 0
MrBedfordVan 0:b9164b348919 69 #define MICROBIT_PIN_EVENT_ON_EDGE 1
MrBedfordVan 0:b9164b348919 70 #define MICROBIT_PIN_EVENT_ON_PULSE 2
MrBedfordVan 0:b9164b348919 71 #define MICROBIT_PIN_EVENT_ON_TOUCH 3
MrBedfordVan 0:b9164b348919 72
MrBedfordVan 0:b9164b348919 73 #define MICROBIT_PIN_EVT_RISE 2
MrBedfordVan 0:b9164b348919 74 #define MICROBIT_PIN_EVT_FALL 3
MrBedfordVan 0:b9164b348919 75 #define MICROBIT_PIN_EVT_PULSE_HI 4
MrBedfordVan 0:b9164b348919 76 #define MICROBIT_PIN_EVT_PULSE_LO 5
MrBedfordVan 0:b9164b348919 77
MrBedfordVan 0:b9164b348919 78 /**
MrBedfordVan 0:b9164b348919 79 * Pin capabilities enum.
MrBedfordVan 0:b9164b348919 80 * Used to determine the capabilities of each Pin as some can only be digital, or can be both digital and analogue.
MrBedfordVan 0:b9164b348919 81 */
MrBedfordVan 0:b9164b348919 82 enum PinCapability{
MrBedfordVan 0:b9164b348919 83 PIN_CAPABILITY_DIGITAL = 0x01,
MrBedfordVan 0:b9164b348919 84 PIN_CAPABILITY_ANALOG = 0x02,
MrBedfordVan 0:b9164b348919 85 PIN_CAPABILITY_AD = PIN_CAPABILITY_DIGITAL | PIN_CAPABILITY_ANALOG,
MrBedfordVan 0:b9164b348919 86 PIN_CAPABILITY_ALL = PIN_CAPABILITY_DIGITAL | PIN_CAPABILITY_ANALOG
MrBedfordVan 0:b9164b348919 87 };
MrBedfordVan 0:b9164b348919 88
MrBedfordVan 0:b9164b348919 89 /**
MrBedfordVan 0:b9164b348919 90 * Class definition for MicroBitPin.
MrBedfordVan 0:b9164b348919 91 *
MrBedfordVan 0:b9164b348919 92 * Commonly represents an I/O pin on the edge connector.
MrBedfordVan 0:b9164b348919 93 */
MrBedfordVan 0:b9164b348919 94 class MicroBitPin : public MicroBitComponent
MrBedfordVan 0:b9164b348919 95 {
MrBedfordVan 0:b9164b348919 96 // The mbed object looking after this pin at any point in time (untyped due to dynamic behaviour).
MrBedfordVan 0:b9164b348919 97 void *pin;
MrBedfordVan 0:b9164b348919 98 PinCapability capability;
MrBedfordVan 0:b9164b348919 99 uint8_t pullMode;
MrBedfordVan 0:b9164b348919 100
MrBedfordVan 0:b9164b348919 101 /**
MrBedfordVan 0:b9164b348919 102 * Disconnect any attached mBed IO from this pin.
MrBedfordVan 0:b9164b348919 103 *
MrBedfordVan 0:b9164b348919 104 * Used only when pin changes mode (i.e. Input/Output/Analog/Digital)
MrBedfordVan 0:b9164b348919 105 */
MrBedfordVan 0:b9164b348919 106 void disconnect();
MrBedfordVan 0:b9164b348919 107
MrBedfordVan 0:b9164b348919 108 /**
MrBedfordVan 0:b9164b348919 109 * Performs a check to ensure that the current Pin is in control of a
MrBedfordVan 0:b9164b348919 110 * DynamicPwm instance, and if it's not, allocates a new DynamicPwm instance.
MrBedfordVan 0:b9164b348919 111 */
MrBedfordVan 0:b9164b348919 112 int obtainAnalogChannel();
MrBedfordVan 0:b9164b348919 113
MrBedfordVan 0:b9164b348919 114 /**
MrBedfordVan 0:b9164b348919 115 * Interrupt handler for when an rise interrupt is triggered.
MrBedfordVan 0:b9164b348919 116 */
MrBedfordVan 0:b9164b348919 117 void onRise();
MrBedfordVan 0:b9164b348919 118
MrBedfordVan 0:b9164b348919 119 /**
MrBedfordVan 0:b9164b348919 120 * Interrupt handler for when an fall interrupt is triggered.
MrBedfordVan 0:b9164b348919 121 */
MrBedfordVan 0:b9164b348919 122 void onFall();
MrBedfordVan 0:b9164b348919 123
MrBedfordVan 0:b9164b348919 124 /**
MrBedfordVan 0:b9164b348919 125 * This member function manages the calculation of the timestamp of a pulse detected
MrBedfordVan 0:b9164b348919 126 * on a pin whilst in IO_STATUS_EVENT_PULSE_ON_EDGE or IO_STATUS_EVENT_ON_EDGE modes.
MrBedfordVan 0:b9164b348919 127 *
MrBedfordVan 0:b9164b348919 128 * @param eventValue the event value to distribute onto the message bus.
MrBedfordVan 0:b9164b348919 129 */
MrBedfordVan 0:b9164b348919 130 void pulseWidthEvent(int eventValue);
MrBedfordVan 0:b9164b348919 131
MrBedfordVan 0:b9164b348919 132 /**
MrBedfordVan 0:b9164b348919 133 * This member function will construct an TimedInterruptIn instance, and configure
MrBedfordVan 0:b9164b348919 134 * interrupts for rise and fall.
MrBedfordVan 0:b9164b348919 135 *
MrBedfordVan 0:b9164b348919 136 * @param eventType the specific mode used in interrupt context to determine how an
MrBedfordVan 0:b9164b348919 137 * edge/rise is processed.
MrBedfordVan 0:b9164b348919 138 *
MrBedfordVan 0:b9164b348919 139 * @return MICROBIT_OK on success
MrBedfordVan 0:b9164b348919 140 */
MrBedfordVan 0:b9164b348919 141 int enableRiseFallEvents(int eventType);
MrBedfordVan 0:b9164b348919 142
MrBedfordVan 0:b9164b348919 143 /**
MrBedfordVan 0:b9164b348919 144 * If this pin is in a mode where the pin is generating events, it will destruct
MrBedfordVan 0:b9164b348919 145 * the current instance attached to this MicroBitPin instance.
MrBedfordVan 0:b9164b348919 146 *
MrBedfordVan 0:b9164b348919 147 * @return MICROBIT_OK on success.
MrBedfordVan 0:b9164b348919 148 */
MrBedfordVan 0:b9164b348919 149 int disableEvents();
MrBedfordVan 0:b9164b348919 150
MrBedfordVan 0:b9164b348919 151 public:
MrBedfordVan 0:b9164b348919 152
MrBedfordVan 0:b9164b348919 153 // mbed PinName of this pin.
MrBedfordVan 0:b9164b348919 154 PinName name;
MrBedfordVan 0:b9164b348919 155
MrBedfordVan 0:b9164b348919 156 /**
MrBedfordVan 0:b9164b348919 157 * Constructor.
MrBedfordVan 0:b9164b348919 158 * Create a MicroBitPin instance, generally used to represent a pin on the edge connector.
MrBedfordVan 0:b9164b348919 159 *
MrBedfordVan 0:b9164b348919 160 * @param id the unique EventModel id of this component.
MrBedfordVan 0:b9164b348919 161 *
MrBedfordVan 0:b9164b348919 162 * @param name the mbed PinName for this MicroBitPin instance.
MrBedfordVan 0:b9164b348919 163 *
MrBedfordVan 0:b9164b348919 164 * @param capability the capabilities this MicroBitPin instance should have.
MrBedfordVan 0:b9164b348919 165 * (PIN_CAPABILITY_DIGITAL, PIN_CAPABILITY_ANALOG, PIN_CAPABILITY_AD, PIN_CAPABILITY_ALL)
MrBedfordVan 0:b9164b348919 166 *
MrBedfordVan 0:b9164b348919 167 * @code
MrBedfordVan 0:b9164b348919 168 * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_ALL);
MrBedfordVan 0:b9164b348919 169 * @endcode
MrBedfordVan 0:b9164b348919 170 */
MrBedfordVan 0:b9164b348919 171 MicroBitPin(int id, PinName name, PinCapability capability);
MrBedfordVan 0:b9164b348919 172
MrBedfordVan 0:b9164b348919 173 /**
MrBedfordVan 0:b9164b348919 174 * Configures this IO pin as a digital output (if necessary) and sets the pin to 'value'.
MrBedfordVan 0:b9164b348919 175 *
MrBedfordVan 0:b9164b348919 176 * @param value 0 (LO) or 1 (HI)
MrBedfordVan 0:b9164b348919 177 *
MrBedfordVan 0:b9164b348919 178 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
MrBedfordVan 0:b9164b348919 179 * if the given pin does not have digital capability.
MrBedfordVan 0:b9164b348919 180 *
MrBedfordVan 0:b9164b348919 181 * @code
MrBedfordVan 0:b9164b348919 182 * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
MrBedfordVan 0:b9164b348919 183 * P0.setDigitalValue(1); // P0 is now HI
MrBedfordVan 0:b9164b348919 184 * @endcode
MrBedfordVan 0:b9164b348919 185 */
MrBedfordVan 0:b9164b348919 186 int setDigitalValue(int value);
MrBedfordVan 0:b9164b348919 187
MrBedfordVan 0:b9164b348919 188 /**
MrBedfordVan 0:b9164b348919 189 * Configures this IO pin as a digital input (if necessary) and tests its current value.
MrBedfordVan 0:b9164b348919 190 *
MrBedfordVan 0:b9164b348919 191 *
MrBedfordVan 0:b9164b348919 192 * @return 1 if this input is high, 0 if input is LO, or MICROBIT_NOT_SUPPORTED
MrBedfordVan 0:b9164b348919 193 * if the given pin does not have digital capability.
MrBedfordVan 0:b9164b348919 194 *
MrBedfordVan 0:b9164b348919 195 * @code
MrBedfordVan 0:b9164b348919 196 * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
MrBedfordVan 0:b9164b348919 197 * P0.getDigitalValue(); // P0 is either 0 or 1;
MrBedfordVan 0:b9164b348919 198 * @endcode
MrBedfordVan 0:b9164b348919 199 */
MrBedfordVan 0:b9164b348919 200 int getDigitalValue();
MrBedfordVan 0:b9164b348919 201
MrBedfordVan 0:b9164b348919 202 /**
MrBedfordVan 0:b9164b348919 203 * Configures this IO pin as a digital input with the specified internal pull-up/pull-down configuraiton (if necessary) and tests its current value.
MrBedfordVan 0:b9164b348919 204 *
MrBedfordVan 0:b9164b348919 205 * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone
MrBedfordVan 0:b9164b348919 206 *
MrBedfordVan 0:b9164b348919 207 * @return 1 if this input is high, 0 if input is LO, or MICROBIT_NOT_SUPPORTED
MrBedfordVan 0:b9164b348919 208 * if the given pin does not have digital capability.
MrBedfordVan 0:b9164b348919 209 *
MrBedfordVan 0:b9164b348919 210 * @code
MrBedfordVan 0:b9164b348919 211 * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
MrBedfordVan 0:b9164b348919 212 * P0.getDigitalValue(PullUp); // P0 is either 0 or 1;
MrBedfordVan 0:b9164b348919 213 * @endcode
MrBedfordVan 0:b9164b348919 214 */
MrBedfordVan 0:b9164b348919 215 int getDigitalValue(PinMode pull);
MrBedfordVan 0:b9164b348919 216
MrBedfordVan 0:b9164b348919 217 /**
MrBedfordVan 0:b9164b348919 218 * Configures this IO pin as an analog/pwm output, and change the output value to the given level.
MrBedfordVan 0:b9164b348919 219 *
MrBedfordVan 0:b9164b348919 220 * @param value the level to set on the output pin, in the range 0 - 1024
MrBedfordVan 0:b9164b348919 221 *
MrBedfordVan 0:b9164b348919 222 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
MrBedfordVan 0:b9164b348919 223 * if the given pin does not have analog capability.
MrBedfordVan 0:b9164b348919 224 */
MrBedfordVan 0:b9164b348919 225 int setAnalogValue(int value);
MrBedfordVan 0:b9164b348919 226
MrBedfordVan 0:b9164b348919 227 /**
MrBedfordVan 0:b9164b348919 228 * Configures this IO pin as an analog/pwm output (if necessary) and configures the period to be 20ms,
MrBedfordVan 0:b9164b348919 229 * with a duty cycle between 500 us and 2500 us.
MrBedfordVan 0:b9164b348919 230 *
MrBedfordVan 0:b9164b348919 231 * 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.
MrBedfordVan 0:b9164b348919 232 *
MrBedfordVan 0:b9164b348919 233 * This range can be modified to fine tune, and also tolerate different servos.
MrBedfordVan 0:b9164b348919 234 *
MrBedfordVan 0:b9164b348919 235 * @param value the level to set on the output pin, in the range 0 - 180.
MrBedfordVan 0:b9164b348919 236 *
MrBedfordVan 0:b9164b348919 237 * @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.
MrBedfordVan 0:b9164b348919 238 *
MrBedfordVan 0:b9164b348919 239 * @param center the center point from which to calculate the lower and upper bounds. Defaults to MICROBIT_PIN_DEFAULT_SERVO_CENTER
MrBedfordVan 0:b9164b348919 240 *
MrBedfordVan 0:b9164b348919 241 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
MrBedfordVan 0:b9164b348919 242 * if the given pin does not have analog capability.
MrBedfordVan 0:b9164b348919 243 */
MrBedfordVan 0:b9164b348919 244 int setServoValue(int value, int range = MICROBIT_PIN_DEFAULT_SERVO_RANGE, int center = MICROBIT_PIN_DEFAULT_SERVO_CENTER);
MrBedfordVan 0:b9164b348919 245
MrBedfordVan 0:b9164b348919 246 /**
MrBedfordVan 0:b9164b348919 247 * Configures this IO pin as an analogue input (if necessary), and samples the Pin for its analog value.
MrBedfordVan 0:b9164b348919 248 *
MrBedfordVan 0:b9164b348919 249 * @return the current analogue level on the pin, in the range 0 - 1024, or
MrBedfordVan 0:b9164b348919 250 * MICROBIT_NOT_SUPPORTED if the given pin does not have analog capability.
MrBedfordVan 0:b9164b348919 251 *
MrBedfordVan 0:b9164b348919 252 * @code
MrBedfordVan 0:b9164b348919 253 * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
MrBedfordVan 0:b9164b348919 254 * P0.getAnalogValue(); // P0 is a value in the range of 0 - 1024
MrBedfordVan 0:b9164b348919 255 * @endcode
MrBedfordVan 0:b9164b348919 256 */
MrBedfordVan 0:b9164b348919 257 int getAnalogValue();
MrBedfordVan 0:b9164b348919 258
MrBedfordVan 0:b9164b348919 259 /**
MrBedfordVan 0:b9164b348919 260 * Determines if this IO pin is currently configured as an input.
MrBedfordVan 0:b9164b348919 261 *
MrBedfordVan 0:b9164b348919 262 * @return 1 if pin is an analog or digital input, 0 otherwise.
MrBedfordVan 0:b9164b348919 263 */
MrBedfordVan 0:b9164b348919 264 int isInput();
MrBedfordVan 0:b9164b348919 265
MrBedfordVan 0:b9164b348919 266 /**
MrBedfordVan 0:b9164b348919 267 * Determines if this IO pin is currently configured as an output.
MrBedfordVan 0:b9164b348919 268 *
MrBedfordVan 0:b9164b348919 269 * @return 1 if pin is an analog or digital output, 0 otherwise.
MrBedfordVan 0:b9164b348919 270 */
MrBedfordVan 0:b9164b348919 271 int isOutput();
MrBedfordVan 0:b9164b348919 272
MrBedfordVan 0:b9164b348919 273 /**
MrBedfordVan 0:b9164b348919 274 * Determines if this IO pin is currently configured for digital use.
MrBedfordVan 0:b9164b348919 275 *
MrBedfordVan 0:b9164b348919 276 * @return 1 if pin is digital, 0 otherwise.
MrBedfordVan 0:b9164b348919 277 */
MrBedfordVan 0:b9164b348919 278 int isDigital();
MrBedfordVan 0:b9164b348919 279
MrBedfordVan 0:b9164b348919 280 /**
MrBedfordVan 0:b9164b348919 281 * Determines if this IO pin is currently configured for analog use.
MrBedfordVan 0:b9164b348919 282 *
MrBedfordVan 0:b9164b348919 283 * @return 1 if pin is analog, 0 otherwise.
MrBedfordVan 0:b9164b348919 284 */
MrBedfordVan 0:b9164b348919 285 int isAnalog();
MrBedfordVan 0:b9164b348919 286
MrBedfordVan 0:b9164b348919 287 /**
MrBedfordVan 0:b9164b348919 288 * Configures this IO pin as a "makey makey" style touch sensor (if necessary)
MrBedfordVan 0:b9164b348919 289 * and tests its current debounced state.
MrBedfordVan 0:b9164b348919 290 *
MrBedfordVan 0:b9164b348919 291 * Users can also subscribe to MicroBitButton events generated from this pin.
MrBedfordVan 0:b9164b348919 292 *
MrBedfordVan 0:b9164b348919 293 * @return 1 if pin is touched, 0 if not, or MICROBIT_NOT_SUPPORTED if this pin does not support touch capability.
MrBedfordVan 0:b9164b348919 294 *
MrBedfordVan 0:b9164b348919 295 * @code
MrBedfordVan 0:b9164b348919 296 * MicroBitMessageBus bus;
MrBedfordVan 0:b9164b348919 297 *
MrBedfordVan 0:b9164b348919 298 * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_ALL);
MrBedfordVan 0:b9164b348919 299 * if(P0.isTouched())
MrBedfordVan 0:b9164b348919 300 * {
MrBedfordVan 0:b9164b348919 301 * //do something!
MrBedfordVan 0:b9164b348919 302 * }
MrBedfordVan 0:b9164b348919 303 *
MrBedfordVan 0:b9164b348919 304 * // subscribe to events generated by this pin!
MrBedfordVan 0:b9164b348919 305 * bus.listen(MICROBIT_ID_IO_P0, MICROBIT_BUTTON_EVT_CLICK, someFunction);
MrBedfordVan 0:b9164b348919 306 * @endcode
MrBedfordVan 0:b9164b348919 307 */
MrBedfordVan 0:b9164b348919 308 int isTouched();
MrBedfordVan 0:b9164b348919 309
MrBedfordVan 0:b9164b348919 310 /**
MrBedfordVan 0:b9164b348919 311 * Configures this IO pin as an analog/pwm output if it isn't already, configures the period to be 20ms,
MrBedfordVan 0:b9164b348919 312 * and sets the pulse width, based on the value it is given.
MrBedfordVan 0:b9164b348919 313 *
MrBedfordVan 0:b9164b348919 314 * @param pulseWidth the desired pulse width in microseconds.
MrBedfordVan 0:b9164b348919 315 *
MrBedfordVan 0:b9164b348919 316 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range, or MICROBIT_NOT_SUPPORTED
MrBedfordVan 0:b9164b348919 317 * if the given pin does not have analog capability.
MrBedfordVan 0:b9164b348919 318 */
MrBedfordVan 0:b9164b348919 319 int setServoPulseUs(int pulseWidth);
MrBedfordVan 0:b9164b348919 320
MrBedfordVan 0:b9164b348919 321 /**
MrBedfordVan 0:b9164b348919 322 * Configures the PWM period of the analog output to the given value.
MrBedfordVan 0:b9164b348919 323 *
MrBedfordVan 0:b9164b348919 324 * @param period The new period for the analog output in milliseconds.
MrBedfordVan 0:b9164b348919 325 *
MrBedfordVan 0:b9164b348919 326 * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the
MrBedfordVan 0:b9164b348919 327 * given pin is not configured as an analog output.
MrBedfordVan 0:b9164b348919 328 */
MrBedfordVan 0:b9164b348919 329 int setAnalogPeriod(int period);
MrBedfordVan 0:b9164b348919 330
MrBedfordVan 0:b9164b348919 331 /**
MrBedfordVan 0:b9164b348919 332 * Configures the PWM period of the analog output to the given value.
MrBedfordVan 0:b9164b348919 333 *
MrBedfordVan 0:b9164b348919 334 * @param period The new period for the analog output in microseconds.
MrBedfordVan 0:b9164b348919 335 *
MrBedfordVan 0:b9164b348919 336 * @return MICROBIT_OK on success, or MICROBIT_NOT_SUPPORTED if the
MrBedfordVan 0:b9164b348919 337 * given pin is not configured as an analog output.
MrBedfordVan 0:b9164b348919 338 */
MrBedfordVan 0:b9164b348919 339 int setAnalogPeriodUs(int period);
MrBedfordVan 0:b9164b348919 340
MrBedfordVan 0:b9164b348919 341 /**
MrBedfordVan 0:b9164b348919 342 * Obtains the PWM period of the analog output in microseconds.
MrBedfordVan 0:b9164b348919 343 *
MrBedfordVan 0:b9164b348919 344 * @return the period on success, or MICROBIT_NOT_SUPPORTED if the
MrBedfordVan 0:b9164b348919 345 * given pin is not configured as an analog output.
MrBedfordVan 0:b9164b348919 346 */
MrBedfordVan 0:b9164b348919 347 int getAnalogPeriodUs();
MrBedfordVan 0:b9164b348919 348
MrBedfordVan 0:b9164b348919 349 /**
MrBedfordVan 0:b9164b348919 350 * Obtains the PWM period of the analog output in milliseconds.
MrBedfordVan 0:b9164b348919 351 *
MrBedfordVan 0:b9164b348919 352 * @return the period on success, or MICROBIT_NOT_SUPPORTED if the
MrBedfordVan 0:b9164b348919 353 * given pin is not configured as an analog output.
MrBedfordVan 0:b9164b348919 354 */
MrBedfordVan 0:b9164b348919 355 int getAnalogPeriod();
MrBedfordVan 0:b9164b348919 356
MrBedfordVan 0:b9164b348919 357 /**
MrBedfordVan 0:b9164b348919 358 * Configures the pull of this pin.
MrBedfordVan 0:b9164b348919 359 *
MrBedfordVan 0:b9164b348919 360 * @param pull one of the mbed pull configurations: PullUp, PullDown, PullNone
MrBedfordVan 0:b9164b348919 361 *
MrBedfordVan 0:b9164b348919 362 * @return MICROBIT_NOT_SUPPORTED if the current pin configuration is anything other
MrBedfordVan 0:b9164b348919 363 * than a digital input, otherwise MICROBIT_OK.
MrBedfordVan 0:b9164b348919 364 */
MrBedfordVan 0:b9164b348919 365 int setPull(PinMode pull);
MrBedfordVan 0:b9164b348919 366
MrBedfordVan 0:b9164b348919 367 /**
MrBedfordVan 0:b9164b348919 368 * Configures the events generated by this MicroBitPin instance.
MrBedfordVan 0:b9164b348919 369 *
MrBedfordVan 0:b9164b348919 370 * 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)
MrBedfordVan 0:b9164b348919 371 * 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)
MrBedfordVan 0:b9164b348919 372 * 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.
MrBedfordVan 0:b9164b348919 373 * MICROBIT_PIN_EVENT_NONE - Disables events for this pin.
MrBedfordVan 0:b9164b348919 374 *
MrBedfordVan 0:b9164b348919 375 * @param eventType One of: MICROBIT_PIN_EVENT_ON_EDGE, MICROBIT_PIN_EVENT_ON_PULSE, MICROBIT_PIN_EVENT_ON_TOUCH, MICROBIT_PIN_EVENT_NONE
MrBedfordVan 0:b9164b348919 376 *
MrBedfordVan 0:b9164b348919 377 * @code
MrBedfordVan 0:b9164b348919 378 * MicroBitMessageBus bus;
MrBedfordVan 0:b9164b348919 379 *
MrBedfordVan 0:b9164b348919 380 * MicroBitPin P0(MICROBIT_ID_IO_P0, MICROBIT_PIN_P0, PIN_CAPABILITY_BOTH);
MrBedfordVan 0:b9164b348919 381 * P0.eventOn(MICROBIT_PIN_EVENT_ON_PULSE);
MrBedfordVan 0:b9164b348919 382 *
MrBedfordVan 0:b9164b348919 383 * void onPulse(MicroBitEvent evt)
MrBedfordVan 0:b9164b348919 384 * {
MrBedfordVan 0:b9164b348919 385 * int duration = evt.timestamp;
MrBedfordVan 0:b9164b348919 386 * }
MrBedfordVan 0:b9164b348919 387 *
MrBedfordVan 0:b9164b348919 388 * bus.listen(MICROBIT_ID_IO_P0, MICROBIT_PIN_EVT_PULSE_HI, onPulse, MESSAGE_BUS_LISTENER_IMMEDIATE)
MrBedfordVan 0:b9164b348919 389 * @endcode
MrBedfordVan 0:b9164b348919 390 *
MrBedfordVan 0:b9164b348919 391 * @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER if the given eventype does not match
MrBedfordVan 0:b9164b348919 392 *
MrBedfordVan 0:b9164b348919 393 * @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,
MrBedfordVan 0:b9164b348919 394 * please use the InterruptIn class supplied by ARM mbed.
MrBedfordVan 0:b9164b348919 395 */
MrBedfordVan 0:b9164b348919 396 int eventOn(int eventType);
MrBedfordVan 0:b9164b348919 397 };
MrBedfordVan 0:b9164b348919 398
MrBedfordVan 0:b9164b348919 399 #endif