Philip Holifield / microbit-dal

from bbc microbit library

Dependencies:   BLE_API mbed-dev-bin nRF51822

Dependents:   microbit

Fork of microbit-dal by Lancaster University

inc/drivers/MicroBitLightSensor.h@75:c700add33ba5, 2018-01-11 (annotated)

Committer:
euxton
Date:
Thu Jan 11 21:54:30 2018 +0000
Revision:
75:c700add33ba5
Parent:
3:d86a4ddc1867 
1st commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jonathan Austin 1:8aa5cdb4ab67 1 /*
Jonathan Austin 1:8aa5cdb4ab67 2 The MIT License (MIT)
Jonathan Austin 1:8aa5cdb4ab67 3
Jonathan Austin 1:8aa5cdb4ab67 4 Copyright (c) 2016 British Broadcasting Corporation.
Jonathan Austin 1:8aa5cdb4ab67 5 This software is provided by Lancaster University by arrangement with the BBC.
Jonathan Austin 1:8aa5cdb4ab67 6
Jonathan Austin 1:8aa5cdb4ab67 7 Permission is hereby granted, free of charge, to any person obtaining a
Jonathan Austin 1:8aa5cdb4ab67 8 copy of this software and associated documentation files (the "Software"),
Jonathan Austin 1:8aa5cdb4ab67 9 to deal in the Software without restriction, including without limitation
Jonathan Austin 1:8aa5cdb4ab67 10 the rights to use, copy, modify, merge, publish, distribute, sublicense,
Jonathan Austin 1:8aa5cdb4ab67 11 and/or sell copies of the Software, and to permit persons to whom the
Jonathan Austin 1:8aa5cdb4ab67 12 Software is furnished to do so, subject to the following conditions:
Jonathan Austin 1:8aa5cdb4ab67 13
Jonathan Austin 1:8aa5cdb4ab67 14 The above copyright notice and this permission notice shall be included in
Jonathan Austin 1:8aa5cdb4ab67 15 all copies or substantial portions of the Software.
Jonathan Austin 1:8aa5cdb4ab67 16
Jonathan Austin 1:8aa5cdb4ab67 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
Jonathan Austin 1:8aa5cdb4ab67 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
Jonathan Austin 1:8aa5cdb4ab67 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
Jonathan Austin 1:8aa5cdb4ab67 20 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
Jonathan Austin 1:8aa5cdb4ab67 22 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
Jonathan Austin 1:8aa5cdb4ab67 23 DEALINGS IN THE SOFTWARE.
Jonathan Austin 1:8aa5cdb4ab67 24 */
Jonathan Austin 1:8aa5cdb4ab67 25
Jonathan Austin 1:8aa5cdb4ab67 26 #ifndef MICROBIT_LIGHT_SENSOR_H
Jonathan Austin 1:8aa5cdb4ab67 27 #define MICROBIT_LIGHT_SENSOR_H
Jonathan Austin 1:8aa5cdb4ab67 28
Jonathan Austin 1:8aa5cdb4ab67 29 #include "mbed.h"
Jonathan Austin 1:8aa5cdb4ab67 30 #include "MicroBitConfig.h"
Jonathan Austin 1:8aa5cdb4ab67 31 #include "MicroBitComponent.h"
Jonathan Austin 1:8aa5cdb4ab67 32 #include "EventModel.h"
Jonathan Austin 1:8aa5cdb4ab67 33 #include "MicroBitMatrixMaps.h"
Jonathan Austin 1:8aa5cdb4ab67 34
Jonathan Austin 1:8aa5cdb4ab67 35 #define MICROBIT_LIGHT_SENSOR_CHAN_NUM 3
Jonathan Austin 1:8aa5cdb4ab67 36 #define MICROBIT_LIGHT_SENSOR_AN_SET_TIME 4000
Jonathan Austin 1:8aa5cdb4ab67 37 #define MICROBIT_LIGHT_SENSOR_TICK_PERIOD 5
Jonathan Austin 1:8aa5cdb4ab67 38
Jonathan Austin 1:8aa5cdb4ab67 39 #define MICROBIT_LIGHT_SENSOR_MAX_VALUE 338
Jonathan Austin 1:8aa5cdb4ab67 40 #define MICROBIT_LIGHT_SENSOR_MIN_VALUE 75
Jonathan Austin 1:8aa5cdb4ab67 41
Jonathan Austin 1:8aa5cdb4ab67 42 /**
Jonathan Austin 1:8aa5cdb4ab67 43 * Class definition for MicroBitLightSensor.
Jonathan Austin 1:8aa5cdb4ab67 44 *
Jonathan Austin 1:8aa5cdb4ab67 45 * This is an object that interleaves light sensing with MicroBitDisplay.
Jonathan Austin 1:8aa5cdb4ab67 46 */
Jonathan Austin 1:8aa5cdb4ab67 47 class MicroBitLightSensor
Jonathan Austin 1:8aa5cdb4ab67 48 {
Jonathan Austin 1:8aa5cdb4ab67 49
Jonathan Austin 1:8aa5cdb4ab67 50 //contains the results from each section of the display
LancasterUniversity 3:d86a4ddc1867 51 int results[MICROBIT_LIGHT_SENSOR_CHAN_NUM];
Jonathan Austin 1:8aa5cdb4ab67 52
Jonathan Austin 1:8aa5cdb4ab67 53 //holds the current channel (also used to index the results array)
Jonathan Austin 1:8aa5cdb4ab67 54 uint8_t chan;
Jonathan Austin 1:8aa5cdb4ab67 55
Jonathan Austin 1:8aa5cdb4ab67 56 //a Timeout which triggers our analogReady() call
Jonathan Austin 1:8aa5cdb4ab67 57 Timeout analogTrigger;
Jonathan Austin 1:8aa5cdb4ab67 58
Jonathan Austin 1:8aa5cdb4ab67 59 //a pointer the currently sensed pin, represented as an AnalogIn
Jonathan Austin 1:8aa5cdb4ab67 60 AnalogIn* sensePin;
Jonathan Austin 1:8aa5cdb4ab67 61
Jonathan Austin 1:8aa5cdb4ab67 62 const MatrixMap &matrixMap;
Jonathan Austin 1:8aa5cdb4ab67 63
Jonathan Austin 1:8aa5cdb4ab67 64 /**
Jonathan Austin 1:8aa5cdb4ab67 65 * After the startSensing method has been called, this method will be called
Jonathan Austin 1:8aa5cdb4ab67 66 * MICROBIT_LIGHT_SENSOR_AN_SET_TIME after.
Jonathan Austin 1:8aa5cdb4ab67 67 *
Jonathan Austin 1:8aa5cdb4ab67 68 * It will then read from the currently selected channel using the AnalogIn
Jonathan Austin 1:8aa5cdb4ab67 69 * that was configured in the startSensing method.
Jonathan Austin 1:8aa5cdb4ab67 70 */
Jonathan Austin 1:8aa5cdb4ab67 71 void analogReady();
Jonathan Austin 1:8aa5cdb4ab67 72
Jonathan Austin 1:8aa5cdb4ab67 73 /**
Jonathan Austin 1:8aa5cdb4ab67 74 * Forcibly disables the AnalogIn, otherwise it will remain in possession
Jonathan Austin 1:8aa5cdb4ab67 75 * of the GPIO channel it is using, meaning that the display will not be
Jonathan Austin 1:8aa5cdb4ab67 76 * able to use a channel (COL).
Jonathan Austin 1:8aa5cdb4ab67 77 *
Jonathan Austin 1:8aa5cdb4ab67 78 * This is required as per PAN 3, details of which can be found here:
Jonathan Austin 1:8aa5cdb4ab67 79 *
Jonathan Austin 1:8aa5cdb4ab67 80 * https://www.nordicsemi.com/eng/nordic/download_resource/24634/5/88440387
Jonathan Austin 1:8aa5cdb4ab67 81 */
Jonathan Austin 1:8aa5cdb4ab67 82 void analogDisable();
Jonathan Austin 1:8aa5cdb4ab67 83
Jonathan Austin 1:8aa5cdb4ab67 84 public:
Jonathan Austin 1:8aa5cdb4ab67 85
Jonathan Austin 1:8aa5cdb4ab67 86 /**
Jonathan Austin 1:8aa5cdb4ab67 87 * Constructor.
Jonathan Austin 1:8aa5cdb4ab67 88 *
Jonathan Austin 1:8aa5cdb4ab67 89 * Create a representation of the light sensor.
Jonathan Austin 1:8aa5cdb4ab67 90 *
Jonathan Austin 1:8aa5cdb4ab67 91 * @param map The mapping information that relates pin inputs/outputs to physical screen coordinates.
Jonathan Austin 1:8aa5cdb4ab67 92 * Defaults to microbitMatrixMap, defined in MicroBitMatrixMaps.h.
Jonathan Austin 1:8aa5cdb4ab67 93 */
Jonathan Austin 1:8aa5cdb4ab67 94 MicroBitLightSensor(const MatrixMap &map);
Jonathan Austin 1:8aa5cdb4ab67 95
Jonathan Austin 1:8aa5cdb4ab67 96 /**
Jonathan Austin 1:8aa5cdb4ab67 97 * This method returns a summed average of the three sections of the display.
Jonathan Austin 1:8aa5cdb4ab67 98 *
Jonathan Austin 1:8aa5cdb4ab67 99 * A section is defined as:
Jonathan Austin 1:8aa5cdb4ab67 100 * ___________________
Jonathan Austin 1:8aa5cdb4ab67 101 * | 1 | | 2 | | 3 |
Jonathan Austin 1:8aa5cdb4ab67 102 * |___|___|___|___|___|
Jonathan Austin 1:8aa5cdb4ab67 103 * | | | | | |
Jonathan Austin 1:8aa5cdb4ab67 104 * |___|___|___|___|___|
Jonathan Austin 1:8aa5cdb4ab67 105 * | 2 | | 3 | | 1 |
Jonathan Austin 1:8aa5cdb4ab67 106 * |___|___|___|___|___|
Jonathan Austin 1:8aa5cdb4ab67 107 * | | | | | |
Jonathan Austin 1:8aa5cdb4ab67 108 * |___|___|___|___|___|
Jonathan Austin 1:8aa5cdb4ab67 109 * | 3 | | 1 | | 2 |
Jonathan Austin 1:8aa5cdb4ab67 110 * |___|___|___|___|___|
Jonathan Austin 1:8aa5cdb4ab67 111 *
Jonathan Austin 1:8aa5cdb4ab67 112 * Where each number represents a different section on the 5 x 5 matrix display.
Jonathan Austin 1:8aa5cdb4ab67 113 *
Jonathan Austin 1:8aa5cdb4ab67 114 * @return returns a value in the range 0 - 255 where 0 is dark, and 255
Jonathan Austin 1:8aa5cdb4ab67 115 * is very bright
Jonathan Austin 1:8aa5cdb4ab67 116 */
Jonathan Austin 1:8aa5cdb4ab67 117 int read();
Jonathan Austin 1:8aa5cdb4ab67 118
Jonathan Austin 1:8aa5cdb4ab67 119 /**
Jonathan Austin 1:8aa5cdb4ab67 120 * The method that is invoked by sending MICROBIT_DISPLAY_EVT_LIGHT_SENSE
Jonathan Austin 1:8aa5cdb4ab67 121 * using the id MICROBIT_ID_DISPLAY.
Jonathan Austin 1:8aa5cdb4ab67 122 *
Jonathan Austin 1:8aa5cdb4ab67 123 * @note this can be manually driven by calling this member function, with
Jonathan Austin 1:8aa5cdb4ab67 124 * a MicroBitEvent using the CREATE_ONLY option of the MicroBitEvent
Jonathan Austin 1:8aa5cdb4ab67 125 * constructor.
Jonathan Austin 1:8aa5cdb4ab67 126 */
Jonathan Austin 1:8aa5cdb4ab67 127 void startSensing(MicroBitEvent);
Jonathan Austin 1:8aa5cdb4ab67 128
Jonathan Austin 1:8aa5cdb4ab67 129 /**
Jonathan Austin 1:8aa5cdb4ab67 130 * A destructor for MicroBitLightSensor.
Jonathan Austin 1:8aa5cdb4ab67 131 *
Jonathan Austin 1:8aa5cdb4ab67 132 * The destructor removes the listener, used by MicroBitLightSensor from the default EventModel.
Jonathan Austin 1:8aa5cdb4ab67 133 */
Jonathan Austin 1:8aa5cdb4ab67 134 ~MicroBitLightSensor();
Jonathan Austin 1:8aa5cdb4ab67 135 };
Jonathan Austin 1:8aa5cdb4ab67 136
LancasterUniversity 3:d86a4ddc1867 137 #endif