From 01ae8f910e1b6d5088b0f3f61280751614dd0766 Mon Sep 17 00:00:00 2001 From: Jaime Albuquerque Date: Sun, 9 Oct 2022 17:16:43 -0300 Subject: [PATCH] shift_reg: add shift_reg component The feature is a driver to interface the microcontroller with shift registers just using 3 pins: Clock, Data and Latch. For further information, please, take a look at the component [README.md](components/shift_reg/README.md). Feature requested by issue #457. --- .github/labeler.yml | 8 + components/shift_reg/.eil.yml | 24 ++ components/shift_reg/CMakeLists.txt | 11 + components/shift_reg/LICENSE | 13 ++ components/shift_reg/README.md | 56 +++++ components/shift_reg/component.mk | 7 + components/shift_reg/shift_reg.c | 209 ++++++++++++++++++ components/shift_reg/shift_reg.h | 125 +++++++++++ examples/shift_reg/default/CMakeLists.txt | 6 + examples/shift_reg/default/Makefile | 6 + examples/shift_reg/default/README.md | 39 ++++ .../shift_reg/default/main/CMakeLists.txt | 2 + examples/shift_reg/default/main/component.mk | 1 + examples/shift_reg/default/main/main.c | 56 +++++ examples/shift_reg/default/sdkconfig.defaults | 1 + 15 files changed, 564 insertions(+) create mode 100644 components/shift_reg/.eil.yml create mode 100644 components/shift_reg/CMakeLists.txt create mode 100644 components/shift_reg/LICENSE create mode 100644 components/shift_reg/README.md create mode 100644 components/shift_reg/component.mk create mode 100644 components/shift_reg/shift_reg.c create mode 100644 components/shift_reg/shift_reg.h create mode 100644 examples/shift_reg/default/CMakeLists.txt create mode 100644 examples/shift_reg/default/Makefile create mode 100644 examples/shift_reg/default/README.md create mode 100644 examples/shift_reg/default/main/CMakeLists.txt create mode 100644 examples/shift_reg/default/main/component.mk create mode 100644 examples/shift_reg/default/main/main.c create mode 100644 examples/shift_reg/default/sdkconfig.defaults diff --git a/.github/labeler.yml b/.github/labeler.yml index af34653a..4a4bfa55 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -536,6 +536,14 @@ labels: - "components/sgp40/**" - "components/sgp40/.eil.yml" - "examples/sgp40/**" + - label: "area:components:shift_reg" + sync: true + matcher: + files: + any: + - "components/shift_reg/**" + - "components/shift_reg/.eil.yml" + - "examples/shift_reg/**" - label: "area:components:sht3x" sync: true matcher: diff --git a/components/shift_reg/.eil.yml b/components/shift_reg/.eil.yml new file mode 100644 index 00000000..7ebad303 --- /dev/null +++ b/components/shift_reg/.eil.yml @@ -0,0 +1,24 @@ +--- +components: + - name: shift_reg + description: Driver for generic shift register to expend I/O by writing or reading from it in a serial communication. + group: misc + groups: [] + code_owners: jaimealbq + depends: + # FIXME conditional depends + - name: driver + - name: log + - name: esp_idf_lib_helpers + thread_safe: yes + targets: + - name: esp32 + - name: esp8266 + - name: esp32s2 + - name: esp32c3 + licenses: + - name: ISC + copyrights: + - author: + name: jaimealbq + year: 2022 diff --git a/components/shift_reg/CMakeLists.txt b/components/shift_reg/CMakeLists.txt new file mode 100644 index 00000000..47c458a3 --- /dev/null +++ b/components/shift_reg/CMakeLists.txt @@ -0,0 +1,11 @@ +if(${IDF_TARGET} STREQUAL esp8266) + set(req esp8266 log esp_idf_lib_helpers) +else() + set(req driver log esp_idf_lib_helpers) +endif() + +idf_component_register( + SRCS shift_reg.c + INCLUDE_DIRS . + REQUIRES ${req} +) diff --git a/components/shift_reg/LICENSE b/components/shift_reg/LICENSE new file mode 100644 index 00000000..2f240711 --- /dev/null +++ b/components/shift_reg/LICENSE @@ -0,0 +1,13 @@ +Copyright (c) 2022 Jaime Albuquerque + +Permission to use, copy, modify, and distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/components/shift_reg/README.md b/components/shift_reg/README.md new file mode 100644 index 00000000..249fef35 --- /dev/null +++ b/components/shift_reg/README.md @@ -0,0 +1,56 @@ +# `Shift Register` +This driver can be used as an interface with a shift register in (still in progress) and out (such as [74HC595](https://www.ti.com/lit/ds/symlink/sn74hc595.pdf)). + +## Usage +To use the library, it needs to be configured before initialize. To do so a `shift_reg_config_s` needs to be set. + +### Configuration +The `shift_reg_config_s` struct store all necessaries configurtions and value of aech register. + +* `uint8_t num_reg` - Number of registers which will be used +* `uint8_t *reg_value` - Vector for the last value of all registers; it can be used for know what is the actual value of the registers +* `struct mode` + * `shift_reg_dir_t dir` - Direction mode of the shift register + * `shift_reg_bit_mode_t bit_mode` - Bit mode +* `struct pin` + * `gpio_num_t clk` - Clock pin + * `gpio_num_t data` - Data/Signal pin + * `gpio_num_t latch` - Latch pin + +#### Direcition mode +The `shift_reg_dir_t` says the direction of the register. +* `SHIFT_DIR_OUTPUT` - Set the register as output +* `SHIFT_DIR_INPUT` - Set the register as input +* `SHIFT_DIR_INPUT_OUTPUT` - Set the register as output and input + +#### First bit configuration +The `shift_reg_bit_mode_t` says the bit mode of the data. +* `SHIFT_BIT_MODE_LSB` - Start send data from the lowest significant bit +* `SHIFT_BIT_MODE_MSB` - Start send data from the most significandt bit + +### Initialization +To initialize the shift register it is going to need to call the `esp_err_t shift_reg_init(shift_reg_config_s *shft)`, by passing the created shift register configurations. + +### De-initialization +Since the `uint8_t *reg_value` is created accordingly of the number of registers, the vector allocate the necessary size in the heap memory, so `esp_err_t shift_reg_deinit(shift_reg_config_s *shft)` can be used to free this memory. + +### Sending the data +To send the intended data, call the `esp_err_t shift_reg_send(uint8_t *data, uint8_t len, shift_reg_config_s *shft)` function, where: +* `data` - the address of the bening of the data +* `len` - the length of the data in bytes +* `shft` - the shift register interface to be used + +**NOTE**: The data sent will be just in the internal memory (register(s)) of the shift register(s), and not reflected in the pins. See lataching pins to see how the pins can be set. + +### Latching pins +To set the pins as it is in the internal memory of the register(s), the function `esp_err_t shift_reg_latch(shift_reg_config_s *shft);` needs to be called. It will be latched by the passed shifter interface. + +## TODO +* [ ] Implement input shift register +* [ ] Interface with [hd44780](../hd44780/) + +# Author +Jaime Albuquerque +* GitHub: [jaimealbq](https://github.com/jaimealbq) +* GitLab: [jaimealbq](https://gitlab.com/jaimealbq) +* LinkedIn: [Jaime Albuquerque](https://www.linkedin.com/in/jaimealbq) diff --git a/components/shift_reg/component.mk b/components/shift_reg/component.mk new file mode 100644 index 00000000..f966ad15 --- /dev/null +++ b/components/shift_reg/component.mk @@ -0,0 +1,7 @@ +COMPONENT_ADD_INCLUDEDIRS = . + +ifdef CONFIG_IDF_TARGET_ESP8266 +COMPONENT_DEPENDS = esp8266 log esp_idf_lib_helpers +else +COMPONENT_DEPENDS = driver log esp_idf_lib_helpers +endif diff --git a/components/shift_reg/shift_reg.c b/components/shift_reg/shift_reg.c new file mode 100644 index 00000000..52169091 --- /dev/null +++ b/components/shift_reg/shift_reg.c @@ -0,0 +1,209 @@ +/* + * Copyright (c) 2022 Jaime Albuquerque + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#include "shift_reg.h" + +static char *tag = "shift_reg"; + +esp_err_t shift_reg_init(shift_reg_config_s *shft) +{ + esp_err_t err = ESP_FAIL; + + if (shft == NULL) + { + ESP_LOGE(tag, "%s: must have the configuration of the shift register", __func__); + err = ESP_ERR_INVALID_ARG; + return err; + } + + shft->reg_value = (uint8_t *)malloc(shft->num_reg); // Create an array with all registers + + if (shft->reg_value == NULL) + { + ESP_LOGE(tag, "%s: no heap memory to allocate reg_value", __func__); + err = ESP_ERR_NO_MEM; + return err; + } + + memset(shft->reg_value, 0, shft->num_reg); // Start all registers as 0 + + gpio_config_t *io_conf = (gpio_config_t *)malloc(sizeof(gpio_config_t)); + + // disable interrupt + io_conf->intr_type = GPIO_INTR_DISABLE; + + switch (shft->mode.dir) + { + case SHIFT_DIR_OUTPUT: + // set as output mode + io_conf->mode = GPIO_MODE_OUTPUT; + uint32_t buf32_0 = 0; + uint32_t buf32_1 = 0; + uint64_t result = 0; + + if (shft->pin.clk >= 32) + buf32_1 |= 1 << (shft->pin.clk - 32); + else + buf32_0 |= 1 << shft->pin.clk; + + if (shft->pin.latch >= 32) + buf32_1 |= 1 << (shft->pin.latch - 32); + else + buf32_0 |= 1 << shft->pin.latch; + + if (shft->pin.data >= 32) + buf32_1 |= 1 << (shft->pin.data - 32); + else + buf32_0 |= 1 << shft->pin.data; + + result = ((uint64_t)buf32_1 << 32) | ((uint64_t)buf32_0 << 0); + + io_conf->pin_bit_mask = result; + + break; + + case SHIFT_DIR_INPUT: + ESP_LOGE(tag, "%s: Input shift register not done yet", __func__); + err = ESP_ERR_NOT_FOUND; + break; + + case SHIFT_DIR_INPUT_OUTPUT: + ESP_LOGE(tag, "%s: Input output shift register not done yet", __func__); + err = ESP_ERR_NOT_FOUND; + break; + + default: + ESP_LOGE(tag, "%s: Mode of shift register not found", __func__); + err = ESP_ERR_NOT_FOUND; + break; + } + // disable pull-down mode + io_conf->pull_down_en = 0; + // disable pull-up mode + io_conf->pull_up_en = 0; + // configure GPIO with the given settings + err = gpio_config(io_conf); + + free(io_conf); + + return err; +} + +esp_err_t shift_reg_deinit(shift_reg_config_s *shft) +{ + free(shft->reg_value); + return ESP_OK; +} + +esp_err_t shift_reg_send(uint8_t *data, uint8_t len, shift_reg_config_s *shft) +{ + esp_err_t err = ESP_FAIL; + + if (shft == NULL || len > shft->num_reg || data == NULL) + { + ESP_LOGE(tag, "%s: must have a valid argument;", __func__); + err = ESP_ERR_INVALID_ARG; + return err; + } + + if (shft->mode.bit_mode == SHIFT_BIT_MODE_MSB) + { + for (uint8_t i = 0; i < len; i++) + { + shift_reg_send8bits(data[i], shft); + shft->reg_value[i] = data[i]; + } + } + else + { + for (int8_t i = len - 1; i >= 0; i--) + { + shift_reg_send8bits(data[i], shft); + shft->reg_value[i] = data[i]; + } + } + + err = ESP_OK; + + return err; +} + +esp_err_t shift_reg_send8bits(uint8_t data, shift_reg_config_s *shft) +{ + esp_err_t err = ESP_FAIL; + + if (shft == NULL) + { + ESP_LOGE(tag, "%s: must have a valid argument;", __func__); + err = ESP_ERR_INVALID_ARG; + return err; + } + + if (shft->mode.bit_mode == SHIFT_BIT_MODE_MSB) + { + // MSB Mode + for (int8_t i = 7; i >= 0; i--) + { + if ((data >> i) & 1) + { + SETPIN(shft->pin.data); + } + else + { + CLRPIN(shft->pin.data); + } + + SETPIN(shft->pin.clk); + _DELAY_US(1); + CLRPIN(shft->pin.clk); + _DELAY_US(1); + } + } + else + { + // LSB Mode + for (int8_t i = 0; i < 8; i++) + { + if ((data >> i) & 1) + { + SETPIN(shft->pin.data); + } + else + { + CLRPIN(shft->pin.data); + } + + SETPIN(shft->pin.clk); + _DELAY_US(1); + CLRPIN(shft->pin.clk); + _DELAY_US(1); + } + } + + err = ESP_OK; + + return err; +} + +esp_err_t shift_reg_latch(shift_reg_config_s *shft) +{ + SETPIN(shft->pin.latch); + _DELAY_US(1); + CLRPIN(shft->pin.latch); + _DELAY_US(1); + + return ESP_OK; +} diff --git a/components/shift_reg/shift_reg.h b/components/shift_reg/shift_reg.h new file mode 100644 index 00000000..32f57799 --- /dev/null +++ b/components/shift_reg/shift_reg.h @@ -0,0 +1,125 @@ +/* + * Copyright (c) 2022 Jaime Albuquerque + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +/** + * @file shift_reg.h + * @defgroup shift_reg shift_reg + * @{ + * + * ESP-IDF driver for generic shift register using 3 pins: + * - data + * - clock + * - latch + * + */ + +#if !defined(__SHIFT_REG__H__) +#define __SHIFT_REG__H__ + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include + +#include +#include +#include +#include + +#define SETPIN(PIN) gpio_set_level(PIN, 1) +#define CLRPIN(PIN) gpio_set_level(PIN, 0) +#define _DELAY_US(x) ets_delay_us(x) + +typedef enum { + SHIFT_DIR_OUTPUT = 0, + SHIFT_DIR_INPUT, + SHIFT_DIR_INPUT_OUTPUT, +} shift_reg_dir_t; + +typedef enum { + SHIFT_BIT_MODE_LSB = 0, + SHIFT_BIT_MODE_MSB, +} shift_reg_bit_mode_t; + +typedef struct { // Configuration of shift register + uint8_t num_reg; // Number of shift registers + uint8_t *reg_value; // Last value of all registers + + struct { + shift_reg_dir_t dir : 2; // Direction mode of the shift register + shift_reg_bit_mode_t bit_mode : 1; // Bit mode + } mode; + + struct { + gpio_num_t clk; // Clock pin + gpio_num_t data; // Data/Signal pin + gpio_num_t latch; // Latch pin + } pin; + +} shift_reg_config_s; + +/** + * @brief Initialize the microcontroller to do the output + * + * @param shft shift register configuration + * @return `ESP_OK` on success + */ +esp_err_t shift_reg_init(shift_reg_config_s *shft); + +/** + * @brief Free used memory + * + * @param shft shift register configuration + * @return `ESP_OK` on success + */ +esp_err_t shift_reg_deinit(shift_reg_config_s *shft); + +/** + * @brief Send the whole data + * + * @param data data vector + * @param len length of the data + * @param shft shift register configuration + * @return `ESP_OK` on success + */ +esp_err_t shift_reg_send(uint8_t *data, uint8_t len, shift_reg_config_s *shft); + +/** + * @brief Send 1 byte of data + * + * @param data 1 byte data + * @param shft shift register configuration + * @return `ESP_OK` on success + */ +esp_err_t shift_reg_send8bits(uint8_t data, shift_reg_config_s *shft); + +/** + * @brief Latch the data inside of the shift register + * + * @param shft shift register configuration + * @return `ESP_OK` on success + */ +esp_err_t shift_reg_latch(shift_reg_config_s *shft); + +#ifdef __cplusplus +} +#endif + +/**@}*/ + +#endif // __SHIFT_REG__H__ diff --git a/examples/shift_reg/default/CMakeLists.txt b/examples/shift_reg/default/CMakeLists.txt new file mode 100644 index 00000000..4cf2c302 --- /dev/null +++ b/examples/shift_reg/default/CMakeLists.txt @@ -0,0 +1,6 @@ +cmake_minimum_required(VERSION 3.5) + +set(EXTRA_COMPONENT_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/../../../components) + +include($ENV{IDF_PATH}/tools/cmake/project.cmake) +project(example_example) diff --git a/examples/shift_reg/default/Makefile b/examples/shift_reg/default/Makefile new file mode 100644 index 00000000..4de3bb31 --- /dev/null +++ b/examples/shift_reg/default/Makefile @@ -0,0 +1,6 @@ +#V := 1 +PROJECT_NAME := example_example + +EXTRA_COMPONENT_DIRS := $(CURDIR)/../../../components + +include $(IDF_PATH)/make/project.mk diff --git a/examples/shift_reg/default/README.md b/examples/shift_reg/default/README.md new file mode 100644 index 00000000..61006c9c --- /dev/null +++ b/examples/shift_reg/default/README.md @@ -0,0 +1,39 @@ +# Shift register out + +## What the example does + +The example shift out periodicly to 2 registers [75HC595](https://www.ti.com/lit/ds/symlink/sn74hc595.pdf) a 2 bytes long number, which gets increments. + +## Configuration + +The following configuration was used: + +| 74HC595 | GPIO | +|---------|------| +| Serial Clock | `GPIO_NUM_12` | +| Data/Signal | `GPIO_NUM_15` | +| Latch | `GPIO_NUM_13` | + +| Mode | enum | +|------|------| +| output | `SHIFT_DIR_OUTPUT` | +| Most Significant Bit (MSB) | `SHIFT_BIT_MODE_MSB` | + +``` +static shift_reg_config_s shifter = { + .num_reg = 2, + .mode = { + .dir = SHIFT_DIR_OUTPUT, + .bit_mode = SHIFT_BIT_MODE_MSB, + }, + .pin = { + .clk = GPIO_NUM_12, + .data = GPIO_NUM_13, + .latch = GPIO_NUM_15, + }, + }; +``` + +## Notes + +For more information, please vist the component directory [shift_reg](/components/shift_reg/). \ No newline at end of file diff --git a/examples/shift_reg/default/main/CMakeLists.txt b/examples/shift_reg/default/main/CMakeLists.txt new file mode 100644 index 00000000..cf2c455c --- /dev/null +++ b/examples/shift_reg/default/main/CMakeLists.txt @@ -0,0 +1,2 @@ +idf_component_register(SRCS "main.c" + INCLUDE_DIRS ".") diff --git a/examples/shift_reg/default/main/component.mk b/examples/shift_reg/default/main/component.mk new file mode 100644 index 00000000..004b18e6 --- /dev/null +++ b/examples/shift_reg/default/main/component.mk @@ -0,0 +1 @@ +COMPONENT_ADD_INCLUDEDIRS = . diff --git a/examples/shift_reg/default/main/main.c b/examples/shift_reg/default/main/main.c new file mode 100644 index 00000000..e6032416 --- /dev/null +++ b/examples/shift_reg/default/main/main.c @@ -0,0 +1,56 @@ +/* + * Copyright (c) 2022 Jaime Albuqueruqe + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#include + +#include +#include + +#include +#include + +static char *tag = "main"; + +void app_main(void) +{ + static shift_reg_config_s shifter = { + .num_reg = 2, + .mode = { + .dir = SHIFT_DIR_OUTPUT, + .bit_mode = SHIFT_BIT_MODE_MSB, + }, + .pin = { + .clk = GPIO_NUM_12, + .data = GPIO_NUM_13, + .latch = GPIO_NUM_15, + }, + }; + + + shift_reg_init(&shifter); + + while (true) { + uint8_t value [2]; + for (uint16_t i = 0; i < 0xFFFF; i++) { + value[0] = (uint8_t) (i & 0xFF); + value[1] = (uint8_t) ((i >> 8) & 0xFF); + shift_reg_send(value, 2, &shifter); + shift_reg_latch(&shifter); + ESP_LOGI(__func__, "reg_value: 0x%02X 0x%02X", shifter.reg_value[0], shifter.reg_value[1]); + vTaskDelay(2 / portTICK_RATE_MS); + } + } +} diff --git a/examples/shift_reg/default/sdkconfig.defaults b/examples/shift_reg/default/sdkconfig.defaults new file mode 100644 index 00000000..cd8cb435 --- /dev/null +++ b/examples/shift_reg/default/sdkconfig.defaults @@ -0,0 +1 @@ +# add required non-default option for the example if any