From c2f0f8de44028bd43c6919feb06a1b9ac180d820 Mon Sep 17 00:00:00 2001 From: KierPalin <45743174+KierPalin@users.noreply.github.com> Date: Wed, 27 Nov 2024 13:56:22 +0000 Subject: [PATCH] Updated documentation for NRF52I2C and NRF52Pin (both .h & .cpp) --- inc/NRF52I2C.h | 61 +++++++---- inc/NRF52Pin.h | 26 ++++- source/NRF52I2C.cpp | 81 ++++++++------ source/NRF52Pin.cpp | 249 ++++++++++++++++++++++++++------------------ 4 files changed, 260 insertions(+), 157 deletions(-) diff --git a/inc/NRF52I2C.h b/inc/NRF52I2C.h index 4fb10b3..c33ecce 100644 --- a/inc/NRF52I2C.h +++ b/inc/NRF52I2C.h @@ -54,9 +54,10 @@ class NRF52I2C : public codal::I2C */ virtual ~NRF52I2C(); - /** Set the frequency of the I2C interface + /** + * Set the frequency of the I2C interface * - * @param frequency The bus frequency in hertz + * @param frequency The bus frequency in hertz. */ virtual int setFrequency(uint32_t frequency); @@ -71,26 +72,30 @@ class NRF52I2C : public codal::I2C /** * Method to release the given pin from a peripheral, if already bound. - * Device drivers should override this method to disconnect themselves from the give pin + * Device drivers should override this method to disconnect themselves from the given pin * to allow it to be used by a different peripheral. * - * @param pin the Pin to be released + * @param pin the Pin to be released. */ virtual int releasePin(Pin &pin) override; /** * Issues a standard, I2C command write to the I2C bus. * This consists of: + * * - Asserting a Start condition on the bus + * * - Selecting the Slave address (as an 8 bit address) + * * - Writing a number of raw data bytes provided + * * - Asserting a Stop condition on the bus * * The CPU will busy wait until the transmission is complete. * - * @param address The 8bit I2C address of the device to write to - * @param data pointer to the bytes to write - * @param len the number of bytes to write + * @param address The 8bit I2C address of the device to write to. This parameter expects the hardware address shifted left once. + * @param data pointer to the bytes to write. + * @param len the number of bytes to write. * @param repeated Suppresses the generation of a STOP condition if set. Default: false; * * @return DEVICE_OK on success, DEVICE_I2C_ERROR if the the write request failed. @@ -100,14 +105,18 @@ class NRF52I2C : public codal::I2C /** * Issues a standard, 2 byte I2C command read to the I2C bus. * This consists of: - * - Asserting a Start condition on the bus - * - Selecting the Slave address (as an 8 bit address) - * - reading "len" bytes of raw 8 bit data into the buffer provided - * - Asserting a Stop condition on the bus + * + * - Asserting a Start condition on the bus. + * + * - Selecting the Slave address (as an 8 bit address). + * + * - reading "len" bytes of raw 8 bit data into the buffer provided. + * + * - Asserting a Stop condition on the bus. * * The CPU will busy wait until the transmission is complete. * - * @param address The 8bit I2C address of the device to read from + * @param address The 8bit I2C address of the device to read from. This parameter expects the hardware address shifted left once. * @param data pointer to store the the bytes read * @param len the number of bytes to read into the buffer * @param repeated Suppresses the generation of a STOP condition if set. Default: false; @@ -119,18 +128,26 @@ class NRF52I2C : public codal::I2C /** * Performs a typical register read operation to the I2C slave device provided. * This consists of: - * - Asserting a Start condition on the bus - * - Selecting the Slave address (as an 8 bit address, I2C WRITE) - * - Selecting a RAM register address in the slave - * - Asserting a Stop condition on the bus - * - Asserting a Start condition on the bus - * - Selecting the Slave address (as an 8 bit address, I2C READ) - * - Performing an 8 bit read operation (of the requested register) - * - Asserting a Stop condition on the bus + * + * - Asserting a Start condition on the bus. + * + * - Selecting the Slave address (as an 8 bit address, I2C WRITE). + * + * - Selecting a RAM register address in the slave. + * + * - Asserting a Stop condition on the bus. + * + * - Asserting a Start condition on the bus. + * + * - Selecting the Slave address (as an 8 bit address, I2C READ). + * + * - Performing an 8 bit read operation (of the requested register). + * + * - Asserting a Stop condition on the bus. * - * The CPU will busy wait until the transmission is complete.. + * The CPU will busy wait until the transmission is complete. * - * @param address 8bit I2C address of the device to read from + * @param address 8bit I2C address of the device to read from. This parameter expects the hardware address shifted left once. * @param reg The 8bit register address of the to read. * @param data A pointer to a memory location to store the result of the read operation * @param length The number of mytes to read diff --git a/inc/NRF52Pin.h b/inc/NRF52Pin.h index f653dc3..6cf446e 100755 --- a/inc/NRF52Pin.h +++ b/inc/NRF52Pin.h @@ -149,6 +149,7 @@ namespace codal * * @code * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * * P0.setDigitalValue(1); // P0 is now HI * @endcode */ @@ -163,6 +164,7 @@ namespace codal * * @code * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * * P0.getDigitalValue(); // P0 is either 0 or 1; * @endcode */ @@ -178,6 +180,7 @@ namespace codal * * @code * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * * P0.getDigitalValue(PullUp); // P0 is either 0 or 1; * @endcode */ @@ -220,6 +223,7 @@ namespace codal * * @code * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * * P0.getAnalogValue(); // P0 is a value in the range of 0 - 1024 * @endcode */ @@ -262,15 +266,21 @@ namespace codal * @return 1 if pin is touched, 0 if not, or DEVICE_NOT_SUPPORTED if this pin does not support touch capability. * * @code + * * DeviceMessageBus bus; * * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_ALL); + * * if(P0.isTouched()) + * * { + * * //do something! + * * } * * // subscribe to events generated by this pin! + * * bus.listen(DEVICE_ID_IO_P0, DEVICE_BUTTON_EVT_CLICK, someFunction); * @endcode */ @@ -285,15 +295,21 @@ namespace codal * @return 1 if pin is touched, 0 if not, or DEVICE_NOT_SUPPORTED if this pin does not support touch capability. * * @code + * * DeviceMessageBus bus; * * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_ALL); + * * if(P0.isTouched()) + * * { - * //do something! + * + * //do something! + * * } * * // subscribe to events generated by this pin! + * * bus.listen(DEVICE_ID_IO_P0, DEVICE_BUTTON_EVT_CLICK, someFunction); * @endcode */ @@ -394,8 +410,11 @@ namespace codal * Configures the events generated by this DevicePin instance. * * DEVICE_PIN_EVENT_ON_EDGE - Configures this pin to a digital input, and generates events whenever a rise/fall is detected on this pin. (DEVICE_PIN_EVT_RISE, DEVICE_PIN_EVT_FALL) + * * DEVICE_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. (DEVICE_PIN_EVT_PULSE_HI, DEVICE_PIN_EVT_PULSE_LO) + * * DEVICE_PIN_EVENT_ON_TOUCH - Configures this pin as a makey makey style touch sensor, in the form of a DeviceButton. Normal button events will be generated using the ID of this pin. + * * DEVICE_PIN_EVENT_NONE - Disables events for this pin. * * @param eventType One of: DEVICE_PIN_EVENT_ON_EDGE, DEVICE_PIN_EVENT_ON_PULSE, DEVICE_PIN_EVENT_ON_TOUCH, DEVICE_PIN_EVENT_NONE @@ -404,14 +423,19 @@ namespace codal * DeviceMessageBus bus; * * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * * P0.eventOn(DEVICE_PIN_EVENT_ON_PULSE); * * void onPulse(Event evt) + * * { + * * int duration = evt.timestamp; + * * } * * bus.listen(DEVICE_ID_IO_P0, DEVICE_PIN_EVT_PULSE_HI, onPulse, MESSAGE_BUS_LISTENER_IMMEDIATE) + * * @endcode * * @return DEVICE_OK on success, or DEVICE_INVALID_PARAMETER if the given eventype does not match diff --git a/source/NRF52I2C.cpp b/source/NRF52I2C.cpp index ed4b611..36c6655 100644 --- a/source/NRF52I2C.cpp +++ b/source/NRF52I2C.cpp @@ -248,22 +248,26 @@ int NRF52I2C::waitForStop(int evt) } /** - * Issues a standard, I2C command write to the I2C bus. - * This consists of: - * - Asserting a Start condition on the bus - * - Selecting the Slave address (as an 8 bit address) - * - Writing a number of raw data bytes provided - * - Asserting a Stop condition on the bus - * - * The CPU will busy wait until the transmission is complete. - * - * @param address The 8bit I2C address of the device to write to - * @param data pointer to the bytes to write - * @param len the number of bytes to write - * @param repeated Suppresses the generation of a STOP condition if set. Default: false; - * - * @return DEVICE_OK on success, DEVICE_I2C_ERROR if the the write request failed. - */ +* Issues a standard, I2C command write to the I2C bus. +* This consists of: + +* - Asserting a Start condition on the bus +* +* - Selecting the Slave address (as an 8 bit address) +* +* - Writing a number of raw data bytes provided +* +* - Asserting a Stop condition on the bus +* +* The CPU will busy wait until the transmission is complete. +* +* @param address The 8bit I2C address of the device to write to. This parameter expects the hardware address shifted left once. +* @param data pointer to the bytes to write. +* @param len the number of bytes to write. +* @param repeated Suppresses the generation of a STOP condition if set. Default: false; +* +* @return DEVICE_OK on success, DEVICE_I2C_ERROR if the the write request failed. +*/ int NRF52I2C::write(uint16_t address, uint8_t *data, int len, bool repeated) { address = address >> 1; @@ -298,14 +302,18 @@ int NRF52I2C::write(uint16_t address, uint8_t *data, int len, bool repeated) /** * Issues a standard, 2 byte I2C command read to the I2C bus. * This consists of: - * - Asserting a Start condition on the bus - * - Selecting the Slave address (as an 8 bit address) - * - reading "len" bytes of raw 8 bit data into the buffer provided - * - Asserting a Stop condition on the bus + * + * - Asserting a Start condition on the bus. + * + * - Selecting the Slave address (as an 8 bit address). + * + * - reading "len" bytes of raw 8 bit data into the buffer provided. + * + * - Asserting a Stop condition on the bus. * * The CPU will busy wait until the transmission is complete. * - * @param address The 8bit I2C address of the device to read from + * @param address The 8bit I2C address of the device to read from. This parameter expects the hardware address shifted left once. * @param data pointer to store the the bytes read * @param len the number of bytes to read into the buffer * @param repeated Suppresses the generation of a STOP condition if set. Default: false; @@ -355,23 +363,30 @@ int NRF52I2C::read(uint16_t address, uint8_t *data, int len, bool repeated) /** * Performs a typical register read operation to the I2C slave device provided. * This consists of: - * - Asserting a Start condition on the bus - * - Selecting the Slave address (as an 8 bit address, I2C WRITE) - * - Selecting a RAM register address in the slave - * - Asserting a Stop condition on the bus - * - Asserting a Start condition on the bus - * - Selecting the Slave address (as an 8 bit address, I2C READ) - * - Performing an 8 bit read operation (of the requested register) - * - Asserting a Stop condition on the bus + * + * - Asserting a Start condition on the bus. + * + * - Selecting the Slave address (as an 8 bit address, I2C WRITE). + * + * - Selecting a RAM register address in the slave. + * + * - Asserting a Stop condition on the bus. + * + * - Asserting a Start condition on the bus. + * + * - Selecting the Slave address (as an 8 bit address, I2C READ). + * + * - Performing an 8 bit read operation (of the requested register). + * + * - Asserting a Stop condition on the bus. * - * The CPU will busy wait until the transmission is complete.. + * The CPU will busy wait until the transmission is complete. * - * @param address 8bit I2C address of the device to read from + * @param address 8bit I2C address of the device to read from. This parameter expects the hardware address shifted left once. * @param reg The 8bit register address of the to read. * @param data A pointer to a memory location to store the result of the read operation * @param length The number of mytes to read - * @param repeated Use a repeated START/START/STOP transaction if true, or independent - * START/STOP/START/STOP transactions if fasle. Default: true + * @param repeated Use a repeated START/START/STOP transaction if true, or independent START/STOP/START/STOP transactions if fasle. Default: true * * @return DEVICE_OK or DEVICE_I2C_ERROR if the the read request failed. */ diff --git a/source/NRF52Pin.cpp b/source/NRF52Pin.cpp index d2418db..57dc202 100755 --- a/source/NRF52Pin.cpp +++ b/source/NRF52Pin.cpp @@ -227,6 +227,7 @@ void NRF52Pin::disconnect() * * @code * Pin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * * P0.setDigitalValue(1); // P0 is now HI * @endcode */ @@ -266,6 +267,7 @@ int NRF52Pin::setDigitalValue(int value) * * @code * Pin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * * P0.getDigitalValue(); // P0 is either 0 or 1; * @endcode */ @@ -293,16 +295,16 @@ int NRF52Pin::getDigitalValue() } /** - * Configures this IO pin as a digital input with the specified internal pull-up/pull-down configuraiton (if necessary) and tests its current value. + * Configures this IO pin as a digital input (if necessary) and tests its current value. * - * @param pull one of the pull configurations: PullMode::Up, PullMode::Down, or PullMode::None. * * @return 1 if this input is high, 0 if input is LO, or DEVICE_NOT_SUPPORTED * if the given pin does not have digital capability. * * @code - * Pin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); - * P0.getDigitalValue(PullMode::Up); + * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * + * P0.getDigitalValue(); // P0 is either 0 or 1; * @endcode */ int NRF52Pin::getDigitalValue(PullMode pull) @@ -381,22 +383,22 @@ int NRF52Pin::setAnalogValue(int value) } /** - * Configures this IO pin as an analog/pwm output (if necessary) and configures the period to be 20ms, - * with a duty cycle between 500 us and 2500 us. - * - * 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. - * - * This range can be modified to fine tune, and also tolerate different servos. - * - * @param value the level to set on the output pin, in the range 0 - 180. - * - * @param range which gives the span of possible values the i.e. the lower and upper bounds (center +/- range/2). Defaults to DEVICE_PIN_DEFAULT_SERVO_RANGE. - * - * @param center the center point from which to calculate the lower and upper bounds. Defaults to DEVICE_PIN_DEFAULT_SERVO_CENTER - * - * @return DEVICE_OK on success, DEVICE_INVALID_PARAMETER if value is out of range, or DEVICE_NOT_SUPPORTED - * if the given pin does not have analog capability. - */ + * Configures this IO pin as an analog/pwm output (if necessary) and configures the period to be 20ms, + * with a duty cycle between 500 us and 2500 us. + * + * 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. + * + * This range can be modified to fine tune, and also tolerate different servos. + * + * @param value the level to set on the output pin, in the range 0 - 180. + * + * @param range which gives the span of possible values the i.e. the lower and upper bounds (center +/- range/2). Defaults to DEVICE_PIN_DEFAULT_SERVO_RANGE. + * + * @param center the center point from which to calculate the lower and upper bounds. Defaults to DEVICE_PIN_DEFAULT_SERVO_CENTER + * + * @return DEVICE_OK on success, DEVICE_INVALID_PARAMETER if value is out of range, or DEVICE_NOT_SUPPORTED + * if the given pin does not have analog capability. + */ int NRF52Pin::setServoValue(int value, int range, int center) { //check if this pin has an analogue mode... @@ -423,16 +425,17 @@ int NRF52Pin::setServoValue(int value, int range, int center) } /** - * Configures this IO pin as an analogue input (if necessary), and samples the Pin for its analog value. - * - * @return the current analogue level on the pin, in the range 0 - 1024, or - * DEVICE_NOT_SUPPORTED if the given pin does not have analog capability. - * - * @code - * Pin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); - * P0.getAnalogValue(); // P0 is a value in the range of 0 - 1024 - * @endcode - */ + * Configures this IO pin as an analogue input (if necessary), and samples the Pin for its analog value. + * + * @return the current analogue level on the pin, in the range 0 - 1024, or + * DEVICE_NOT_SUPPORTED if the given pin does not have analog capability. + * + * @code + * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * + * P0.getAnalogValue(); // P0 is a value in the range of 0 - 1024 + * @endcode + */ int NRF52Pin::getAnalogValue() { @@ -500,28 +503,33 @@ int NRF52Pin::isAnalog() return (status & (IO_STATUS_ANALOG_IN | IO_STATUS_ANALOG_OUT)) == 0 ? 0 : 1; } - /** - * Configures this IO pin as a "makey makey" style touch sensor (if necessary) - * and tests its current debounced state. - * - * Users can also subscribe to DeviceButton events generated from this pin. - * - * @return 1 if pin is touched, 0 if not, or DEVICE_NOT_SUPPORTED if this pin does not support touch capability. - * - * @code - * DeviceMessageBus bus; - * - * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_ALL); - * if(P0.isTouched()) - * { - * //do something! - * } - * - * // subscribe to events generated by this pin! - * bus.listen(DEVICE_ID_IO_P0, DEVICE_BUTTON_EVT_CLICK, someFunction); - * @endcode - */ + * Configures this IO pin as a "makey makey" style touch sensor (if necessary) + * and tests its current debounced state. + * + * Users can also subscribe to DeviceButton events generated from this pin. + * + * @return 1 if pin is touched, 0 if not, or DEVICE_NOT_SUPPORTED if this pin does not support touch capability. + * + * @code + * + * DeviceMessageBus bus; + * + * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_ALL); + * + * if(P0.isTouched()) + * + * { + * + * //do something! + * + * } + * + * // subscribe to events generated by this pin! + * + * bus.listen(DEVICE_ID_IO_P0, DEVICE_BUTTON_EVT_CLICK, someFunction); + * @endcode + */ int NRF52Pin::isTouched() { // Maintain the last type of sensing used. @@ -530,27 +538,32 @@ int NRF52Pin::isTouched() /** - * Configures this IO pin as a "makey makey" style touch sensor (if necessary) - * and tests its current debounced state. - * - * Users can also subscribe to Button events generated from this pin. - * - * @param mode Type of sensing to use (resistive or capacitative) - * @return 1 if pin is touched, 0 if not, or DEVICE_NOT_SUPPORTED if this pin does not support touch capability. - * - * @code - * DeviceMessageBus bus; - * - * Pin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_ALL); - * if(P0.isTouched()) - * { - * //do something! - * } - * - * // subscribe to events generated by this pin! - * bus.listen(DEVICE_ID_IO_P0, DEVICE_BUTTON_EVT_CLICK, someFunction); - * @endcode - */ + * Configures this IO pin as a "makey makey" style touch sensor (if necessary) + * and tests its current debounced state. + * + * Users can also subscribe to DeviceButton events generated from this pin. + * @param mode Type of sensing to use (resistive or capacitative) + * @return 1 if pin is touched, 0 if not, or DEVICE_NOT_SUPPORTED if this pin does not support touch capability. + * + * @code + * + * DeviceMessageBus bus; + * + * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_ALL); + * + * if(P0.isTouched()) + * + * { + * + * //do something! + * + * } + * + * // subscribe to events generated by this pin! + * + * bus.listen(DEVICE_ID_IO_P0, DEVICE_BUTTON_EVT_CLICK, someFunction); + * @endcode + */ int NRF52Pin::isTouched(TouchMode touchMode) { //check if this pin has a touch mode... @@ -588,12 +601,39 @@ int NRF52Pin::isTouched(TouchMode touchMode) return ((Button *)obj)->isPressed(); } + +/** + * Configures this pin as a "makey makey" style touch sensor (if required) and tests if at any point the pin has + * been touched _since the last time_ this was called. + * + * Note that holding the pin in the 'touched' state will only generate one event, so this can be viewed as a kind + * of 'falling edge' detection, where only a not-touched followed by a touched event must occur to increment the count. + * + * For this to work, the there must be two sequential `wasTouched` calls with no other pin + * mode changes in between for this pin, otherwise the touch count will be reset. + * + * @return int The number of touch events since the last call. + */ int NRF52Pin::wasTouched() { // Maintain the last type of sensing used. return wasTouched(status & IO_STATUS_CAPACITATIVE_TOUCH ? TouchMode::Capacitative : TouchMode::Resistive); } + +/** + * Configures this pin as a "makey makey" style touch sensor (if required) and tests if at any point the pin has + * been touched _since the last time_ this was called. + * + * Note that holding the pin in the 'touched' state will only generate one event, so this can be viewed as a kind + * of 'falling edge' detection, where only a not-touched followed by a touched event must occur to increment the count. + * + * For this to work, the there must be two sequential `wasTouched` calls with the same parameter used with no other pin + * mode changes in between for this pin, otherwise the touch count will be reset. + * + * @param touchMode Which touch mode to use this pin in. + * @return int The number of touch events since the last call. + */ int NRF52Pin::wasTouched(TouchMode touchMode) { TouchMode currentTouchMode = (status & IO_STATUS_CAPACITATIVE_TOUCH) ? TouchMode::Capacitative : TouchMode::Resistive; @@ -859,36 +899,43 @@ int NRF52Pin::disableEvents() return DEVICE_OK; } - /** - * Configures the events generated by this Pin instance. - * - * DEVICE_PIN_EVENT_ON_EDGE - Configures this pin to a digital input, and generates events whenever a rise/fall is detected on this pin. (DEVICE_PIN_EVT_RISE, DEVICE_PIN_EVT_FALL) - * DEVICE_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. (DEVICE_PIN_EVT_PULSE_HI, DEVICE_PIN_EVT_PULSE_LO) - * DEVICE_PIN_EVENT_ON_TOUCH - Configures this pin as a makey makey style touch sensor, in the form of a Button. Normal button events will be generated using the ID of this pin. - * DEVICE_PIN_EVENT_NONE - Disables events for this pin. - * - * @param eventType One of: DEVICE_PIN_EVENT_ON_EDGE, DEVICE_PIN_EVENT_ON_PULSE, DEVICE_PIN_EVENT_ON_TOUCH, DEVICE_PIN_EVENT_NONE - * - * @code - * DeviceMessageBus bus; - * - * Pin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); - * P0.eventOn(DEVICE_PIN_EVENT_ON_PULSE); - * - * void onPulse(Event evt) - * { - * int duration = evt.timestamp; - * } - * - * bus.listen(DEVICE_ID_IO_P0, DEVICE_PIN_EVT_PULSE_HI, onPulse, MESSAGE_BUS_LISTENER_IMMEDIATE) - * @endcode - * - * @return DEVICE_OK on success, or DEVICE_INVALID_PARAMETER if the given eventype does not match - * - * @note In the DEVICE_PIN_EVENT_ON_PULSE mode, the smallest pulse that was reliably detected was 85us, around 5khz. If more precision is required, - * please use the InterruptIn class supplied by ARM mbed. - */ + * Configures the events generated by this DevicePin instance. + * + * DEVICE_PIN_EVENT_ON_EDGE - Configures this pin to a digital input, and generates events whenever a rise/fall is detected on this pin. (DEVICE_PIN_EVT_RISE, DEVICE_PIN_EVT_FALL) + * + * DEVICE_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. (DEVICE_PIN_EVT_PULSE_HI, DEVICE_PIN_EVT_PULSE_LO) + * + * DEVICE_PIN_EVENT_ON_TOUCH - Configures this pin as a makey makey style touch sensor, in the form of a DeviceButton. Normal button events will be generated using the ID of this pin. + * + * DEVICE_PIN_EVENT_NONE - Disables events for this pin. + * + * @param eventType One of: DEVICE_PIN_EVENT_ON_EDGE, DEVICE_PIN_EVENT_ON_PULSE, DEVICE_PIN_EVENT_ON_TOUCH, DEVICE_PIN_EVENT_NONE + * + * @code + * DeviceMessageBus bus; + * + * DevicePin P0(DEVICE_ID_IO_P0, DEVICE_PIN_P0, PIN_CAPABILITY_BOTH); + * + * P0.eventOn(DEVICE_PIN_EVENT_ON_PULSE); + * + * void onPulse(Event evt) + * + * { + * + * int duration = evt.timestamp; + * + * } + * + * bus.listen(DEVICE_ID_IO_P0, DEVICE_PIN_EVT_PULSE_HI, onPulse, MESSAGE_BUS_LISTENER_IMMEDIATE) + * + * @endcode + * + * @return DEVICE_OK on success, or DEVICE_INVALID_PARAMETER if the given eventype does not match + * + * @note In the DEVICE_PIN_EVENT_ON_PULSE mode, the smallest pulse that was reliably detected was 85us, around 5khz. If more precision is required, + * please use the InterruptIn class supplied by ARM mbed. + */ int NRF52Pin::eventOn(int eventType) { switch(eventType)