Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/inc/drivers/DynamicPwm.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 #include "mbed.h"
MrBedfordVan 0:b9164b348919 27 #include "MicroBitConfig.h"
MrBedfordVan 0:b9164b348919 28
MrBedfordVan 0:b9164b348919 29 #ifndef MICROBIT_DYNAMIC_PWM_H
MrBedfordVan 0:b9164b348919 30 #define MICROBIT_DYNAMIC_PWM_H
MrBedfordVan 0:b9164b348919 31
MrBedfordVan 0:b9164b348919 32 #define NO_PWMS 3
MrBedfordVan 0:b9164b348919 33 #define MICROBIT_DEFAULT_PWM_PERIOD 20000
MrBedfordVan 0:b9164b348919 34
MrBedfordVan 0:b9164b348919 35 enum PwmPersistence
MrBedfordVan 0:b9164b348919 36 {
MrBedfordVan 0:b9164b348919 37 PWM_PERSISTENCE_TRANSIENT = 1,
MrBedfordVan 0:b9164b348919 38 PWM_PERSISTENCE_PERSISTENT = 2,
MrBedfordVan 0:b9164b348919 39 };
MrBedfordVan 0:b9164b348919 40
MrBedfordVan 0:b9164b348919 41 /**
MrBedfordVan 0:b9164b348919 42 * Class definition for DynamicPwm.
MrBedfordVan 0:b9164b348919 43 *
MrBedfordVan 0:b9164b348919 44 * This class addresses a few issues found in the underlying libraries.
MrBedfordVan 0:b9164b348919 45 * This provides the ability for a neat, clean swap between PWM channels.
MrBedfordVan 0:b9164b348919 46 */
MrBedfordVan 0:b9164b348919 47 class DynamicPwm : public PwmOut
MrBedfordVan 0:b9164b348919 48 {
MrBedfordVan 0:b9164b348919 49 private:
MrBedfordVan 0:b9164b348919 50 static DynamicPwm* pwms[NO_PWMS];
MrBedfordVan 0:b9164b348919 51 static uint8_t lastUsed;
MrBedfordVan 0:b9164b348919 52 static uint16_t sharedPeriod;
MrBedfordVan 0:b9164b348919 53 uint8_t flags;
MrBedfordVan 0:b9164b348919 54 float lastValue;
MrBedfordVan 0:b9164b348919 55
MrBedfordVan 0:b9164b348919 56
MrBedfordVan 0:b9164b348919 57
MrBedfordVan 0:b9164b348919 58 /**
MrBedfordVan 0:b9164b348919 59 * An internal constructor used when allocating a new DynamicPwm instance.
MrBedfordVan 0:b9164b348919 60 *
MrBedfordVan 0:b9164b348919 61 * @param pin the name of the pin for the pwm to target
MrBedfordVan 0:b9164b348919 62 *
MrBedfordVan 0:b9164b348919 63 * @param persistance the level of persistence for this pin PWM_PERSISTENCE_PERSISTENT (can not be replaced until freed, should only be used for system services really.)
MrBedfordVan 0:b9164b348919 64 * or PWM_PERSISTENCE_TRANSIENT (can be replaced at any point if a channel is required.)
MrBedfordVan 0:b9164b348919 65 */
MrBedfordVan 0:b9164b348919 66 DynamicPwm(PinName pin, PwmPersistence persistence = PWM_PERSISTENCE_TRANSIENT);
MrBedfordVan 0:b9164b348919 67
MrBedfordVan 0:b9164b348919 68 public:
MrBedfordVan 0:b9164b348919 69
MrBedfordVan 0:b9164b348919 70 /**
MrBedfordVan 0:b9164b348919 71 * Redirects the pwm channel to point at a different pin.
MrBedfordVan 0:b9164b348919 72 *
MrBedfordVan 0:b9164b348919 73 * @param pin the desired pin to output a PWM wave.
MrBedfordVan 0:b9164b348919 74 *
MrBedfordVan 0:b9164b348919 75 * @code
MrBedfordVan 0:b9164b348919 76 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 77 * pwm->redirect(p0); // pwm is now produced on p0
MrBedfordVan 0:b9164b348919 78 * @endcode
MrBedfordVan 0:b9164b348919 79 */
MrBedfordVan 0:b9164b348919 80 void redirect(PinName pin);
MrBedfordVan 0:b9164b348919 81
MrBedfordVan 0:b9164b348919 82
MrBedfordVan 0:b9164b348919 83 /**
MrBedfordVan 0:b9164b348919 84 * Creates a new DynamicPwm instance, or reuses an existing instance that
MrBedfordVan 0:b9164b348919 85 * has a persistence level of PWM_PERSISTENCE_TRANSIENT.
MrBedfordVan 0:b9164b348919 86 *
MrBedfordVan 0:b9164b348919 87 * @param pin the name of the pin for the pwm to target
MrBedfordVan 0:b9164b348919 88 *
MrBedfordVan 0:b9164b348919 89 * @param persistance the level of persistence for this pin PWM_PERSISTENCE_PERSISTENT (can not be replaced until freed, should only be used for system services really.)
MrBedfordVan 0:b9164b348919 90 * or PWM_PERSISTENCE_TRANSIENT (can be replaced at any point if a channel is required.)
MrBedfordVan 0:b9164b348919 91 *
MrBedfordVan 0:b9164b348919 92 * @return a pointer to the first available free pwm channel - or the first one that can be reallocated. If
MrBedfordVan 0:b9164b348919 93 * no channels are available, NULL is returned.
MrBedfordVan 0:b9164b348919 94 *
MrBedfordVan 0:b9164b348919 95 * @code
MrBedfordVan 0:b9164b348919 96 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 97 * @endcode
MrBedfordVan 0:b9164b348919 98 */
MrBedfordVan 0:b9164b348919 99 static DynamicPwm* allocate(PinName pin, PwmPersistence persistence = PWM_PERSISTENCE_TRANSIENT);
MrBedfordVan 0:b9164b348919 100
MrBedfordVan 0:b9164b348919 101 /**
MrBedfordVan 0:b9164b348919 102 * Frees this DynamicPwm instance for reuse.
MrBedfordVan 0:b9164b348919 103 *
MrBedfordVan 0:b9164b348919 104 * @code
MrBedfordVan 0:b9164b348919 105 * DynamicPwm* pwm = DynamicPwm::allocate();
MrBedfordVan 0:b9164b348919 106 * pwm->release();
MrBedfordVan 0:b9164b348919 107 * @endcode
MrBedfordVan 0:b9164b348919 108 */
MrBedfordVan 0:b9164b348919 109 void release();
MrBedfordVan 0:b9164b348919 110
MrBedfordVan 0:b9164b348919 111 /**
MrBedfordVan 0:b9164b348919 112 * A lightweight wrapper around the super class' write in order to capture the value
MrBedfordVan 0:b9164b348919 113 *
MrBedfordVan 0:b9164b348919 114 * @param value the duty cycle percentage in floating point format.
MrBedfordVan 0:b9164b348919 115 *
MrBedfordVan 0:b9164b348919 116 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if value is out of range
MrBedfordVan 0:b9164b348919 117 *
MrBedfordVan 0:b9164b348919 118 * @code
MrBedfordVan 0:b9164b348919 119 * DynamicPwm* pwm = DynamicPwm::allocate();
MrBedfordVan 0:b9164b348919 120 * pwm->write(0.5);
MrBedfordVan 0:b9164b348919 121 * @endcode
MrBedfordVan 0:b9164b348919 122 */
MrBedfordVan 0:b9164b348919 123 int write(float value);
MrBedfordVan 0:b9164b348919 124
MrBedfordVan 0:b9164b348919 125 /**
MrBedfordVan 0:b9164b348919 126 * Retreives the PinName associated with this DynamicPwm instance.
MrBedfordVan 0:b9164b348919 127 *
MrBedfordVan 0:b9164b348919 128 * @code
MrBedfordVan 0:b9164b348919 129 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 130 *
MrBedfordVan 0:b9164b348919 131 * // returns the PinName n.
MrBedfordVan 0:b9164b348919 132 * pwm->getPinName();
MrBedfordVan 0:b9164b348919 133 * @endcode
MrBedfordVan 0:b9164b348919 134 *
MrBedfordVan 0:b9164b348919 135 * @note This should be used to check that the DynamicPwm instance has not
MrBedfordVan 0:b9164b348919 136 * been reallocated for use in another part of a program.
MrBedfordVan 0:b9164b348919 137 */
MrBedfordVan 0:b9164b348919 138 PinName getPinName();
MrBedfordVan 0:b9164b348919 139
MrBedfordVan 0:b9164b348919 140 /**
MrBedfordVan 0:b9164b348919 141 * Retreives the last value that has been written to this DynamicPwm instance.
MrBedfordVan 0:b9164b348919 142 * in the range 0 - 1023 inclusive.
MrBedfordVan 0:b9164b348919 143 *
MrBedfordVan 0:b9164b348919 144 * @code
MrBedfordVan 0:b9164b348919 145 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 146 * pwm->write(0.5);
MrBedfordVan 0:b9164b348919 147 *
MrBedfordVan 0:b9164b348919 148 * // will return 512.
MrBedfordVan 0:b9164b348919 149 * pwm->getValue();
MrBedfordVan 0:b9164b348919 150 * @endcode
MrBedfordVan 0:b9164b348919 151 */
MrBedfordVan 0:b9164b348919 152 int getValue();
MrBedfordVan 0:b9164b348919 153
MrBedfordVan 0:b9164b348919 154 /**
MrBedfordVan 0:b9164b348919 155 * Retreives the current period in use by the entire PWM module in microseconds.
MrBedfordVan 0:b9164b348919 156 *
MrBedfordVan 0:b9164b348919 157 * Example:
MrBedfordVan 0:b9164b348919 158 * @code
MrBedfordVan 0:b9164b348919 159 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 160 * pwm->getPeriod();
MrBedfordVan 0:b9164b348919 161 * @endcode
MrBedfordVan 0:b9164b348919 162 */
MrBedfordVan 0:b9164b348919 163 int getPeriodUs();
MrBedfordVan 0:b9164b348919 164
MrBedfordVan 0:b9164b348919 165 /**
MrBedfordVan 0:b9164b348919 166 * Retreives the current period in use by the entire PWM module in milliseconds.
MrBedfordVan 0:b9164b348919 167 *
MrBedfordVan 0:b9164b348919 168 * Example:
MrBedfordVan 0:b9164b348919 169 * @code
MrBedfordVan 0:b9164b348919 170 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 171 * pwm->setPeriodUs(20000);
MrBedfordVan 0:b9164b348919 172 *
MrBedfordVan 0:b9164b348919 173 * // will return 20000
MrBedfordVan 0:b9164b348919 174 * pwm->getPeriod();
MrBedfordVan 0:b9164b348919 175 * @endcode
MrBedfordVan 0:b9164b348919 176 */
MrBedfordVan 0:b9164b348919 177 int getPeriod();
MrBedfordVan 0:b9164b348919 178
MrBedfordVan 0:b9164b348919 179 /**
MrBedfordVan 0:b9164b348919 180 * Sets the period used by the WHOLE PWM module.
MrBedfordVan 0:b9164b348919 181 *
MrBedfordVan 0:b9164b348919 182 * @param period the desired period in microseconds.
MrBedfordVan 0:b9164b348919 183 *
MrBedfordVan 0:b9164b348919 184 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if period is out of range
MrBedfordVan 0:b9164b348919 185 *
MrBedfordVan 0:b9164b348919 186 * Example:
MrBedfordVan 0:b9164b348919 187 * @code
MrBedfordVan 0:b9164b348919 188 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 189 *
MrBedfordVan 0:b9164b348919 190 * // period now is 20ms
MrBedfordVan 0:b9164b348919 191 * pwm->setPeriodUs(20000);
MrBedfordVan 0:b9164b348919 192 * @endcode
MrBedfordVan 0:b9164b348919 193 *
MrBedfordVan 0:b9164b348919 194 * @note Any changes to the period will AFFECT ALL CHANNELS.
MrBedfordVan 0:b9164b348919 195 */
MrBedfordVan 0:b9164b348919 196 int setPeriodUs(int period);
MrBedfordVan 0:b9164b348919 197
MrBedfordVan 0:b9164b348919 198 /**
MrBedfordVan 0:b9164b348919 199 * Sets the period used by the WHOLE PWM module. Any changes to the period will AFFECT ALL CHANNELS.
MrBedfordVan 0:b9164b348919 200 *
MrBedfordVan 0:b9164b348919 201 * @param period the desired period in milliseconds.
MrBedfordVan 0:b9164b348919 202 *
MrBedfordVan 0:b9164b348919 203 * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if period is out of range
MrBedfordVan 0:b9164b348919 204 *
MrBedfordVan 0:b9164b348919 205 * Example:
MrBedfordVan 0:b9164b348919 206 * @code
MrBedfordVan 0:b9164b348919 207 * DynamicPwm* pwm = DynamicPwm::allocate(PinName n);
MrBedfordVan 0:b9164b348919 208 *
MrBedfordVan 0:b9164b348919 209 * // period now is 20ms
MrBedfordVan 0:b9164b348919 210 * pwm->setPeriod(20);
MrBedfordVan 0:b9164b348919 211 * @endcode
MrBedfordVan 0:b9164b348919 212 */
MrBedfordVan 0:b9164b348919 213 int setPeriod(int period);
MrBedfordVan 0:b9164b348919 214 };
MrBedfordVan 0:b9164b348919 215
MrBedfordVan 0:b9164b348919 216 #endif