Merge pull request #1 from portapack-mayhem/external-module-api

Initial development of PortaPack - Module Develoment Kit

.gitignore

@@ -0,0 +1,2 @@
+**/build/
+

src/CMakeLists.txt

@@ -0,0 +1,11 @@
+cmake_minimum_required(VERSION 3.5)
+
+project(standalone_apps)
+
+add_subdirectory(pacman)
+
+add_custom_target(
+	standalone_apps
+	DEPENDS pacman_app
+)
+

src/portapack-external-module/.devcontainer/Dockerfile

@@ -0,0 +1,47 @@
+FROM espressif/idf
+
+ARG DEBIAN_FRONTEND=nointeractive
+ARG CONTAINER_USER=esp
+ARG USER_UID=1050
+ARG USER_GID=$USER_UID
+
+RUN apt-get update \
+  && apt install -y -q \
+  cmake \
+  git \
+  libglib2.0-0 \
+  libnuma1 \
+  libpixman-1-0 \
+  && rm -rf /var/lib/apt/lists/*
+
+# QEMU
+ENV QEMU_REL=esp_develop_8.2.0_20240122
+ENV QEMU_SHA256=e7c72ef5705ad1444d391711088c8717fc89f42e9bf6d1487f9c2a326b8cfa83
+ENV QEMU_DIST=qemu-xtensa-softmmu-${QEMU_REL}-x86_64-linux-gnu.tar.xz
+ENV QEMU_URL=https://github.com/espressif/qemu/releases/download/esp-develop-8.2.0-20240122/${QEMU_DIST}
+
+ENV LC_ALL=C.UTF-8
+ENV LANG=C.UTF-8
+
+RUN wget --no-verbose ${QEMU_URL} \
+  && echo "${QEMU_SHA256} *${QEMU_DIST}" | sha256sum --check --strict - \
+  && tar -xf $QEMU_DIST -C /opt \
+  && rm ${QEMU_DIST}
+
+ENV PATH=/opt/qemu/bin:${PATH}
+
+RUN groupadd --gid $USER_GID $CONTAINER_USER \
+  && adduser --uid $USER_UID --gid $USER_GID --disabled-password --gecos "" ${CONTAINER_USER} \
+  && usermod -a -G root $CONTAINER_USER && usermod -a -G dialout $CONTAINER_USER
+
+RUN chmod -R 775 /opt/esp/python_env/
+
+USER ${CONTAINER_USER}
+ENV USER=${CONTAINER_USER}
+WORKDIR /home/${CONTAINER_USER}
+
+RUN echo "source /opt/esp/idf/export.sh > /dev/null 2>&1" >> ~/.bashrc
+
+ENTRYPOINT [ "/opt/esp/entrypoint.sh" ]
+
+CMD ["/bin/bash", "-c"]

src/portapack-external-module/.devcontainer/devcontainer.json

@@ -0,0 +1,36 @@
+{
+	"name": "ESP-IDF QEMU",
+	"build": {
+		"dockerfile": "Dockerfile"
+	},
+	"customizations": {
+		"vscode": {
+			"settings": {
+				"terminal.integrated.defaultProfile.linux": "bash",
+				"idf.espIdfPath": "/opt/esp/idf",
+				"idf.customExtraPaths": "",
+				"idf.pythonBinPath": "/opt/esp/python_env/idf5.4_py3.12_env/bin/python",
+				"idf.toolsPath": "/opt/esp",
+				"idf.gitPath": "/usr/bin/git"
+			},
+			"extensions": [
+				"espressif.esp-idf-extension"
+			]
+		},
+		"codespaces": {
+			"settings": {
+				"terminal.integrated.defaultProfile.linux": "bash",
+				"idf.espIdfPath": "/opt/esp/idf",
+				"idf.customExtraPaths": "",
+				"idf.pythonBinPath": "/opt/esp/python_env/idf5.4_py3.12_env/bin/python",
+				"idf.toolsPath": "/opt/esp",
+				"idf.gitPath": "/usr/bin/git"
+			},
+			"extensions": [
+				"espressif.esp-idf-extension",
+				"espressif.esp-idf-web"
+			]
+		}
+	},
+	"runArgs": ["--privileged"]
+}

src/portapack-external-module/CMakeLists.txt

@@ -0,0 +1,6 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(portapack-external-module)

src/portapack-external-module/README.md

@@ -0,0 +1,197 @@
+| Supported Targets | ESP32 | ESP32-C3 | ESP32-C6 | ESP32-H2 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- |
+
+# I2C Self-Test Example
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+## Overview
+
+This example demonstrates basic usage of I2C driver by running two tasks on I2C bus:
+
+1. Read external I2C sensor, here we take the BH1750 ambient light sensor (GY-30 module) for an example.
+2. Use one of the ESP device's I2C port (master mode) to read and write another I2C port (slave mode) in ESP device.
+
+If you have a new I2C application to go (for example, read the temperature data from external sensor with I2C interface), try this as a basic template, then add your own code.
+
+## How to use example
+
+### Hardware Required
+
+To run this example, you should have one ESP development board (e.g. ESP32-WROVER Kit) or ESP core board (e.g. ESP32-DevKitC). Optionally, you can also connect an external sensor. Here we choose the BH1750 just as an example. BH1750 is a digital ambient light sensor. For more information about it, you can read the [datasheet](http://rohmfs.rohm.com/en/products/databook/datasheet/ic/sensor/light/bh1721fvc-e.pdf) of this sensor.
+
+#### Pin Assignment(esp32, esp32s2):
+
+**Note:** The following pin assignments are used by default, you can change these  in the `menuconfig` .
+
+|                           | SDA    | SCL    |
+| ------------------------- | ------ | ------ |
+| ESP32/ESP32-S2 I2C Master | GPIO18 | GPIO19 |
+| ESP32/ESP32-S2 I2C Slave  | GPIO4  | GPIO5  |
+| BH1750 Sensor             | SDA    | SCL    |
+
+- slave:
+  - GPIO4 is assigned as the data signal of I2C slave port
+  - GPIO5 is assigned as the clock signal of I2C slave port
+- master:
+  - GPIO18 is assigned as the data signal of I2C master port
+  - GPIO19 is assigned as the clock signal of I2C master port
+
+- Connection:
+  - connect GPIO18 with GPIO4
+  - connect GPIO19 with GPIO5
+  - connect SDA/SCL of BH1750 sensor with GPIO18/GPIO19
+
+**Note:** It is recommended to add external pull-up resistors for SDA/SCL pins to make the communication more stable, though the driver will enable internal pull-up resistors.
+
+#### Pin Assignment(esp32s3, esp32h2):
+
+**Note:** The following pin assignments are used by default, you can change these  in the `menuconfig` .
+
+|                                    | SDA    | SCL    |
+| ---------------------------------- | ------ | ------ |
+| ESP32-S3/ESP32-H2 I2C Master       | GPIO1  | GPIO2  |
+| ESP32-S3/ESP32-H2 I2C Slave        | GPIO4  | GPIO5  |
+| BH1750 Sensor                      | SDA    | SCL    |
+
+- slave:
+  - GPIO4 is assigned as the data signal of I2C slave port
+  - GPIO5 is assigned as the clock signal of I2C slave port
+- master:
+  - GPIO1 is assigned as the data signal of I2C master port
+  - GPIO2 is assigned as the clock signal of I2C master port
+
+- Connection:
+  - connect GPIO1 with GPIO4
+  - connect GPIO2 with GPIO5
+  - connect SDA/SCL of BH1750 sensor with GPIO18/GPIO19
+
+**Note:** It is recommended to add external pull-up resistors for SDA/SCL pins to make the communication more stable, though the driver will enable internal pull-up resistors.
+
+#### Pin Assignment(esp32c3, esp32c2):
+
+**Note:** The following pin assignments are used by default, you can change these in the `menuconfig` .
+
+|                                             | SDA    | SCL    |
+| ------------------------------------------- | ------ | ------ |
+| ESP32-C3/ESP32-C2 I2C Master(Slave)         | GPIO5  | GPIO6  |
+| BH1750 Sensor                               | SDA    | SCL    |
+
+- master:
+  - GPIO5 is assigned to the data signal of the I2C master port
+  - GPIO6 is assigned to the clock signal of the I2C master port
+
+- Connection:
+  - connect SDA/SCL of BH1750 sensor to GPIO5/GPIO6
+
+**Note:** There is only one i2c device on ESP32-C3/ESP32-C2, so it is not possible to perform any ESP32/ESP32-S2 self-test example from this repo. However it is possible to test I2C with external devices. If you find anything wrong with your device, please try connecting external pull-up resistors.
+
+### Configure the project
+
+Open the project configuration menu (`idf.py menuconfig`). Then go into `Example Configuration` menu.
+
+- In the `I2C Master` submenu, you can set the pin number of SDA/SCL according to your board. Also you can modify the I2C port number and freauency of the master.
+- In the `I2C Slave` submenu, you can set the pin number of SDA/SCL according to your board. Also you can modify the I2C port number and address of the slave.
+- In the `BH1750 Sensor` submenu, you can choose the slave address of BH1750 accroding to the pin level of ADDR pin (if the pin level of ADDR is low then the address is `0x23`, otherwise it is `0x5c`). Here you can also control the operation mode of BH1750, each mode has a different resolution and measurement time. For example, in the `One Time L-Resolution` mode, the resolution is 4 Lux and measurement time is typically 16ms (higher resolution means longer measurement time). For more information, you can consult the datasheet of BH1750.
+
+
+### Build and Flash
+
+Enter `idf.py -p PORT flash monitor` to build, flash and monitor the project.
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+```bash
+I (6495) i2c-example: TASK[1] test cnt: 1
+*******************
+TASK[1]  MASTER READ SENSOR( BH1750 )
+*******************
+data_h: 01
+data_l: d0
+sensor val: 386.67 [Lux]
+I (6695) i2c-example: TASK[0] test cnt: 2
+*******************
+TASK[0]  MASTER READ SENSOR( BH1750 )
+*******************
+data_h: 01
+data_l: d0
+sensor val: 386.67 [Lux]
+*******************
+TASK[0]  MASTER READ FROM SLAVE
+*******************
+====TASK[0] Slave buffer data ====
+00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
+10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
+20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
+30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f
+40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f
+50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f
+60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f
+70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f
+
+====TASK[0] Master read ====
+00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
+10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
+20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
+30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f
+40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f
+50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f
+60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f
+70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f
+
+*******************
+TASK[1]  MASTER READ FROM SLAVE
+*******************
+====TASK[1] Slave buffer data ====
+00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
+10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
+20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
+30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f
+40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f
+50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f
+60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f
+70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f
+
+====TASK[1] Master read ====
+00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
+10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
+20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
+30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f
+40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f
+50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f
+60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f
+70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f
+
+*******************
+TASK[0]  MASTER WRITE TO SLAVE
+*******************
+----TASK[0] Master write ----
+0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18 19
+1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 28 29
+2a 2b 2c 2d 2e 2f 30 31 32 33 34 35 36 37 38 39
+3a 3b 3c 3d 3e 3f 40 41 42 43 44 45 46 47 48 49
+4a 4b 4c 4d 4e 4f 50 51 52 53 54 55 56 57 58 59
+5a 5b 5c 5d 5e 5f 60 61 62 63 64 65 66 67 68 69
+6a 6b 6c 6d 6e 6f 70 71 72 73 74 75 76 77 78 79
+7a 7b 7c 7d 7e 7f 80 81 82 83 84 85 86 87 88 89
+
+----TASK[0] Slave read: [128] bytes ----
+0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18 19
+1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 28 29
+2a 2b 2c 2d 2e 2f 30 31 32 33 34 35 36 37 38 39
+3a 3b 3c 3d 3e 3f 40 41 42 43 44 45 46 47 48 49
+4a 4b 4c 4d 4e 4f 50 51 52 53 54 55 56 57 58 59
+5a 5b 5c 5d 5e 5f 60 61 62 63 64 65 66 67 68 69
+6a 6b 6c 6d 6e 6f 70 71 72 73 74 75 76 77 78 79
+7a 7b 7c 7d 7e 7f 80 81 82 83 84 85 86 87 88 89
+```
+
+## Troubleshooting
+
+- BH1750 has two I2C address, which is decided by the voltage level of `ADDR` pin at start up. Make sure to check your schemetic before run this example.
+
+(For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you as soon as possible.)

src/portapack-external-module/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(SRCS "main.cpp" "i2c_slave_driver.c"
+                       INCLUDE_DIRS "." "../../uart/build"
+                       REQUIRES driver esp_driver_i2c)