| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| #ifndef _BLINK_H_ |
| #define _BLINK_H_ |
| |
| #include <stdbool.h> |
| #include <os/os.h> |
| |
| /** |
| * The blink, allow led blinking (or beeper). |
| * You will need to leverage the gpio or the pwm (with/without easing) |
| * to control the line, this is done by providing an implementation |
| * of the "on" and "off" methods. |
| * |
| * Blinking is done by pushing callouts to the event queue, so |
| * the 'on' and 'off' methods will be executed in the event queue context. |
| * (default queue can be configured with the blink_evq_set()) |
| * |
| * |
| * A small example: |
| * |
| * void led_set_state(bool state) { |
| * hal_gpio_write(LED_2, !state); |
| * } |
| * hal_gpio_init_out(LED_2, 1); |
| * |
| * blink_t blink = { |
| * .set_state = led_set_state, |
| * .separator = 2, |
| * }; |
| * |
| * blink_init(&blink); |
| * blink_code(&blink, BLINK_STREAK(1,1,3), BLINK_SCHEDULED_WAIT_BLINK); |
| * blink_dotdash(&blink, "...---...", BLINK_SCHEDULED_WAIT_BLINK); |
| */ |
| |
| /** |
| * Fast time unit: 0.1s |
| */ |
| #define BLINK_UNIT_FAST (OS_TICKS_PER_SEC / 10) |
| /** |
| * Medium time unit: 0.25s |
| */ |
| #define BLINK_UNIT_MEDIUM (OS_TICKS_PER_SEC / 4) |
| /** |
| * Slow time unit: 0.5s |
| */ |
| #define BLINK_UNIT_SLOW (OS_TICKS_PER_SEC / 2) |
| |
| /** |
| * Immediately start the new blinking sequence, whatever |
| * is the current blinking state (but still ensure separator time). |
| */ |
| #define BLINK_SCHEDULED_IMMEDIATE 1 |
| /** |
| * Start the blinking sequence when on an 'off' state. |
| */ |
| #define BLINK_SCHEDULED_WAIT_BLINK 2 |
| /** |
| * Start the blinking sequence when the current sequence |
| * is considered as finished (or whatever is considered |
| * acceptable for the current blinking processor) |
| */ |
| #define BLINK_SCHEDULED_WAIT_SEQUENCE 3 |
| |
| /** |
| * @brief Hold a blink definition. |
| * |
| * @details Use the BLINK macro to assign a value. |
| */ |
| typedef uint32_t blink_code_t; |
| |
| /** |
| * @brief Retrieve the blink length |
| * |
| * @param blink blink value |
| * @return Blink length |
| */ |
| #define BLINK_GET_LENGTH(blink) ((blink >> 0) & 0xFF) |
| |
| /** |
| * @brief Retrieve the blink delay |
| * |
| * @param blink blink value |
| * @return Blink delay |
| */ |
| #define BLINK_GET_DELAY(blink) ((blink >> 8) & 0xFF) |
| |
| /** |
| * @brief Retrieve the blink wait |
| * |
| * @param blink blink value |
| * @return Blink wait |
| */ |
| #define BLINK_GET_WAIT(blink) ((blink >> 16) & 0xFF) |
| |
| /** |
| * @brief Retrieve the blink count |
| * |
| * @param blink blink value |
| * @return Blink count |
| */ |
| #define BLINK_GET_COUNT(blink) ((blink >> 24) & 0x0F) |
| |
| /** |
| * @brief Define the blink value |
| * |
| * @note Special meaning is given to the zero value for |
| * length, delay, wait, or count. |
| * Only the following set containing 0 is well defined: |
| * L / D / C / W |
| * 0 / 0 / 0 / 0 = Always off |
| * 1 / 0 / 0 / 0 = Always on |
| * x / y / 0 / . = Continous blinking on (length) / off (delay) |
| * x / . / 1 / . = Blink once |
| * x / y / z / 0 = Repeat z time the on/off sequence and stop |
| * |
| * @details Create the blinking sequence: |
| * (on[length] / (off[delay] / on[length]){count-1} off[wait])+ |
| * |
| * @param length duration of led on (1 .. 255) |
| * @param delay duration of led off (betwenn led on) (1 .. 255) |
| * @param count define a group of consecutive on/off (1 .. 15) |
| * @param wait duration of led off (between group) (1 .. 255) |
| */ |
| #define BLINK(length, delay, count, wait) ((length << 0) | \ |
| (delay << 8) | \ |
| (wait << 16) | \ |
| (count << 24)) |
| |
| /** |
| * Always ON |
| */ |
| #define BLINK_ON BLINK(1, 0, 0, 0) |
| |
| /** |
| * Always OFF |
| */ |
| #define BLINK_OFF BLINK(0, 0, 0, 0) |
| |
| /** |
| * Blink once and stop |
| * |
| * @param length duration of 'on' state |
| */ |
| #define BLINK_ONCE(length) BLINK(length, 0, 1, 0) |
| |
| /** |
| * Continuously blink |
| * |
| * @param length duration of 'on' state |
| * @param delay duration of 'off' state |
| */ |
| #define BLINK_CONTINUOUS(length, delay) BLINK(length, delay, 0, 0) |
| |
| /** |
| * Blink n-time and stop. |
| * |
| * @param length duration of 'on' state |
| * @param delay duration of 'off' state |
| * @param count number of blinks |
| */ |
| #define BLINK_STREAK(length, delay, count) BLINK(length, delay, count, 0) |
| |
| /* Forward declaration */ |
| struct blink; |
| |
| typedef struct blink blink_t; |
| |
| /* |
| * Compute time for next on/off duration |
| */ |
| typedef bool (*blink_onoff_t)(blink_t *blink, uint16_t *on, uint16_t *off); |
| |
| /** |
| * Function to set the led/beeper/... state (on / off) |
| */ |
| typedef void (*blink_state_t )(bool state); |
| |
| /** |
| * Blink handler |
| */ |
| struct blink { |
| /** |
| * Function to drive the led/beeper/... state (on / off) |
| */ |
| blink_state_t set_state; |
| /** |
| * Unit of time for blinks (in ticks). |
| */ |
| uint32_t time_unit; |
| /** |
| * Blink separator. Delay between two consecutive blink requests. |
| */ |
| uint16_t separator; |
| /* |
| * Last blink time |
| */ |
| os_time_t last_time; |
| /* |
| * Running |
| */ |
| struct { |
| blink_onoff_t onoff; |
| void *data; |
| uint16_t step; |
| uint8_t flags; |
| } running; |
| /* |
| * Pending |
| */ |
| struct { |
| blink_onoff_t onoff; |
| void *data; |
| uint8_t scheduled; |
| } next; |
| /* |
| * Mutex |
| */ |
| struct os_mutex mutex; |
| /* |
| * Callout for 'on'/'off' |
| */ |
| struct os_callout onoff_callout; |
| /* |
| * State value for callout |
| */ |
| bool c_state; |
| int32_t c_next; |
| }; |
| |
| /** |
| * Specify an alternate default queue for processing blink callback. |
| * |
| * @note If not called, the default OS eventq will be used: os_eventq_dflt_get() |
| * |
| * @note Calling this function afer blink initialisation has been done |
| * will result in an undefined behaviour. |
| */ |
| void blink_evq_set(struct os_eventq *evq); |
| |
| /** |
| * Blink handler initialisation. |
| * |
| * @param blink blink handler |
| */ |
| void blink_init(blink_t *blink); |
| |
| /** |
| * Start blinking sequence. |
| * |
| * @param blink blink handler |
| * @param code Blinkink sequence description |
| * (see: BLINK macro) |
| * @param scheduled when to start the blinking sequence: |
| * o BLINK_SCHEDULED_IMMEDIATE |
| * o BLINK_SCHEDULED_WAIT_BLINK |
| * o BLINK_SCHEDULED_WAIT_SEQUENCE |
| */ |
| void blink_code(blink_t *blink, blink_code_t code, int scheduled); |
| |
| /** |
| * Schedule blinking sequence using short and long blink. |
| * Can be used to emit morse code. |
| * |
| * @param blink blink handler |
| * @param dotdash string using '.' and '-' |
| * @param scheduled when to start the blinking sequence: |
| * o BLINK_SCHEDULED_IMMEDIATE |
| * o BLINK_SCHEDULED_WAIT_BLINK |
| * o BLINK_SCHEDULED_WAIT_SEQUENCE |
| */ |
| void blink_dotdash(blink_t *blink, char *dotdash, int scheduled); |
| |
| /** |
| * Stop the blinking sequence. |
| * |
| * @note In this case the 'separator' time won't be applied. |
| * |
| * @param blink blink handler |
| * @param scheduled when to stop the blinking sequence: |
| * o BLINK_SCHEDULED_IMMEDIATE |
| * o BLINK_SCHEDULED_WAIT_BLINK |
| * o BLINK_SCHEDULED_WAIT_SEQUENCE |
| */ |
| void blink_stop(blink_t *blink, int scheduled); |
| |
| #endif |
