├── .gitignore ├── LICENSE ├── README.md ├── _sidebar.md ├── developer-toolchains ├── arduino.md ├── developer-toolchains.md ├── esp-idf.md ├── img │ ├── arduino_board_manager.png │ ├── esp-idf-install.png │ └── esp-idf-setup.png ├── micropython.md ├── toit.md └── zephyr.md ├── faq ├── communication.md ├── gnss-gps.md ├── hardware-features.md ├── modem-update.md ├── power-management.md ├── software-development.md └── troubleshooting.md ├── file └── gm02s_at_commands.pdf ├── guides ├── cellular_connectivity.md ├── getting_started.md ├── guides.md └── img │ └── getting_started_walter_sim_insert.jpg ├── hardware ├── hardware.md ├── img │ ├── hardware_pinout.svg │ ├── walter-feels-transparent-01.png │ ├── walter-functionality-numbered-stroke.svg │ └── walter-testpoints.svg ├── walter.md └── walter_feels.md └── walter-modem ├── arduino_esp-idf ├── arduino_esp-idf.md ├── reference │ ├── http.md │ ├── mqtt.md │ ├── reference.md │ └── sockets.md └── setup │ ├── arduino.md │ ├── esp-idf.md │ ├── img │ ├── arduino_examples.png │ ├── arduino_library_manager.png │ ├── board_selection.png │ └── board_selection_screen.png │ └── setup.md ├── micropython ├── img │ ├── thonny-lib-open.png │ ├── thonny-new-dir.png │ └── thonny-upload-to-lib.png ├── micropython.md ├── reference │ ├── common.md │ ├── gnss.md │ ├── http.md │ ├── mqtt.md │ ├── pdp_ctx_management.md │ ├── reference.md │ ├── sim_and_network.md │ ├── sleep.md │ ├── sockets.md │ └── tls_and_certificates.md └── setup.md └── walter-modem.md /.gitignore: -------------------------------------------------------------------------------- 1 | index.html 2 | .markdownlint.json -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | This repository contains all information and documentation about Walter and 4 | additional motherboards for Walter. Walter is a board designed by 5 | [DPTechnics](https://www.dptechnics.com) which combines an 6 | [ESP32-S3](https://www.espressif.com/en/products/socs/esp32-s3) and 7 | a [Sequans Monarch 2](https://www.sequans.com/products/monarch-2-gm02sp) in a 8 | small form factor IoT module. This gives Walter a vast amount of wireless 9 | connectivity options such as: 10 | 11 | - Bluetooth Low Energy 5.0 12 | - 1T1R WiFi b/g/n 13 | - LTE Cat-M1 (LTE-M) 14 | - LTE Cat-NB1 (NB-IoT rel. 13) 15 | - LTE Cat-NB2 (NB-IoT rel. 14), ready for rel. 15 16 | - GNSS receiver (GPS and Galileo) 17 | 18 | Besides these you get all the goodies from the ESP32-S3 chip such as SPI, I2S, 19 | I2C, PWM, RMT, ADC, UART, SD/MMC host and TWAI. 20 | 21 | We design and manufacture Walter in Belgium and guarantee that the board will be 22 | available for a minimum of 10 years. This makes Walter a solid choice to design 23 | your next LPWAN IoT product with. 24 | 25 | All documentation for Walter is open source and we welcome all contributions are 26 | more than welcome. 27 | 28 | ## Structure 29 | 30 | All documentation is created in markdown and it is visualized by docsify on the 31 | quickspot website. The documentation website can be found here: 32 | 33 | -------------------------------------------------------------------------------- /_sidebar.md: -------------------------------------------------------------------------------- 1 | * [Guides](/guides/guides.md) 2 | * [Getting Started](/) 3 | * [Cellular Connectivity](/guides/cellular_connectivity.md) 4 | * [Hardware](/hardware/hardware.md) 5 | * [Walter](/hardware/walter.md) 6 | * [Walter Feels](/hardware/walter_feels.md) 7 | * [Development Toolchains](/developer-toolchains/developer-toolchains.md) 8 | * [Arduino](/developer-toolchains/arduino.md) 9 | * [ESP IDF](/developer-toolchains/esp-idf.md) 10 | * [Micropython](/developer-toolchains/micropython.md) 11 | * [Toit](/developer-toolchains/toit.md) 12 | * [Zephyr](/developer-toolchains/zephyr.md) 13 | * [Walter Modem library](/walter-modem/walter-modem.md) 14 | * [Arduino & ESP-IDF](/walter-modem/arduino_esp-idf/arduino_esp-idf.md) 15 | * [Setup](/walter-modem/arduino_esp-idf/setup/setup.md) 16 | * [Arduino](/walter-modem/arduino_esp-idf/setup/arduino.md) 17 | * [ESP-IDF](/walter-modem/arduino_esp-idf/setup/esp-idf.md) 18 | * [API Reference](/walter-modem/arduino_esp-idf/reference/reference.md) 19 | * [Sockets](/walter-modem/arduino_esp-idf/reference/sockets.md) 20 | * [HTTP](/walter-modem/arduino_esp-idf/reference/http.md) 21 | * [MQTT](/walter-modem/arduino_esp-idf/reference/mqtt.md) 22 | * [Micropython](/walter-modem/micropython/micropython.md) 23 | * [Setup](/walter-modem/micropython/setup.md) 24 | * [API Reference](/walter-modem/micropython/reference/reference.md) 25 | * [Common](/walter-modem/micropython/reference/common.md) 26 | * [SIM & Network](/walter-modem/micropython/reference/sim_and_network.md) 27 | * [PDP Context Management](/walter-modem/micropython/reference/pdp_ctx_management.md) 28 | * [GNSS](/walter-modem/micropython/reference/gnss.md) 29 | * [Sockets](/walter-modem/micropython/reference/sockets.md) 30 | * [HTTP](/walter-modem/micropython/reference/http.md) 31 | * [MQTT](/walter-modem/micropython/reference/mqtt.md) 32 | * [Sleep](/walter-modem/micropython/reference/sleep.md) 33 | * [TLS & Certtificates](/walter-modem/micropython/reference/tls_and_certificates.md) 34 | * Frequently Asked Questionss 35 | * [Communication](/faq/communication.md) 36 | * [GNNS / GPS](/faq/gnss-gps.md) 37 | * [Hardware Features](/faq/hardware-features.md) 38 | * [Power Management](/faq/power-management.md) 39 | * [Software Development](/faq/software-development.md) 40 | * [Troubleshooting](/faq/troubleshooting.md) 41 | * [Modem update](/faq/modem-update.md) 42 | -------------------------------------------------------------------------------- /developer-toolchains/arduino.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | This guide walks you through setting up the 4 | Arduino Integrated Development Environment (IDE)\ 5 | along with the necessary components for working with ESP32 boards. 6 | 7 | It covers downloading the IDE, installing board managers, 8 | and configuring your environment. 9 | 10 | --- 11 | 12 | ## Guide 13 | 14 | ### 1. Download and Install the Arduino IDE 15 | 16 | - Visit the [Arduino Software page](https://www.arduino.cc/en/software). 17 | - Download the version appropriate for your operating system 18 | (Windows, Mac OS, or Linux). 19 | - Follow the installation instructions provided on the website. 20 | 21 | ### 2. Installing the ESP32 Board Manager 22 | 23 | To work with ESP32-based boards, you need to install the ESP32 board manager: 24 | 25 | ![arduino_board_manager](img/arduino_board_manager.png) 26 | 27 | ### 3. General IDE Configuration 28 | 29 | > [!NOTE] 30 | > The board configuration can be set automatically by pressing the 31 | > `Get Board Info` button in the `Tools` tab. 32 | 33 | - **Board:** ESP32S3 Dev Module 34 | - **Upload Speed:** 921600 35 | - **USB Mode:** Hardware CDC and JTAG 36 | - **USB CDC On Boot:** Enabled 37 | - **Upload Mode:** UART0 / Hardware CDC 38 | - **CPU Frequency:** 240MHz (WiFi) 39 | - **Flash Mode:** QIO 80MHz 40 | - **Flash Size:** 16MB (128Mb) 41 | - **Partition Scheme:** 16M Flash (2MB APP/12.5MB FATFS) 42 | - **Core Debug Level:** (Select your preferred level) 43 | - **PSRAM:** QSPI PSRAM 44 | - **Arduino Runs On:** Core 1 45 | - **Events Run On:** Core 1 46 | - **Erase All Flash Before Sketch Upload:** Enabled 47 | - **JTAG Adapter:** Integrated USB JTAG 48 | - **Zigbee Mode:** Disabled 49 | -------------------------------------------------------------------------------- /developer-toolchains/developer-toolchains.md: -------------------------------------------------------------------------------- 1 | ## Development Toolchains 2 | 3 | - [Arduino](/developer-toolchains/arduino.md) 4 | - [ESP-IDF](/developer-toolchains/esp-idf.md) 5 | - [Micropython](/developer-toolchains/micropython.md) 6 | - [Toit](/developer-toolchains/toit.md) 7 | - [Zephyr](/developer-toolchains/zephyr.md) 8 | -------------------------------------------------------------------------------- /developer-toolchains/esp-idf.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | This walks you through setting up the ESP-IDF development environment in VS Code. 4 | 5 | It covers installing the ESP-IDF extension, creating a new projec 6 | and configuring the device target. 7 | 8 | --- 9 | 10 | ## Guide 11 | 12 | ### 1. Installing the ESP-IDF Extension 13 | 14 | > [!NOTE] 15 | > VS Code is recommended for an easier ESP-IDF experience. 16 | 17 | 1. Install the 18 | [ESP-IDF extension](https://marketplace.visualstudio.com/items?itemName=espressifesp-idf-extension) 19 | from the VS Code Marketplace. 20 | 2. After installation, the extension will prompt you to set it up. 21 | 3. Select the latest ESP-IDF version and click **Install**. 22 | 4. The extension will automatically install all necessary tools. 23 | 24 | ![ESP-IDF Setup](img/esp-idf-setup.png) 25 | 26 | ![ESP-IDF Install](img/esp-idf-install.png) 27 | 28 | ### 2. Creating a New Project 29 | 30 | To create a new project, open the VS Code command palette (Quickmenu) and select:\ 31 | `>ESP-IDF: Create project from Extension Template` 32 | 33 | Then select `template-app` as your starter project. 34 | 35 | ### 3. Setting the Device Target 36 | 37 | Each new project must have the device target set to **ESP32S3**:\ 38 | `>ESP-IDF: Set Espressif Device Target` 39 | 40 | Your ESP-IDF environment in VS Code is now set up and ready for development. 41 | -------------------------------------------------------------------------------- /developer-toolchains/img/arduino_board_manager.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/developer-toolchains/img/arduino_board_manager.png -------------------------------------------------------------------------------- /developer-toolchains/img/esp-idf-install.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/developer-toolchains/img/esp-idf-install.png -------------------------------------------------------------------------------- /developer-toolchains/img/esp-idf-setup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/developer-toolchains/img/esp-idf-setup.png -------------------------------------------------------------------------------- /developer-toolchains/micropython.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | [MicroPython](https://micropython.org/) is a lightweight implementation 4 | of the Python programming language that is optimised to run on microcontrollers 5 | and in constrained environments. 6 | 7 | This guide walks you through setting up MicroPython on Walter and 8 | running your first script. 9 | 10 | --- 11 | 12 | ## Guide 13 | 14 | ### 1. Install Python and required tools 15 | 16 | #### Python 17 | 18 | 19 | 20 | ##### **Windows** 21 | 22 | Download and install Python from the 23 | [official website](https://www.python.org/downloads/). 24 | During installation, ensure you select the option to add Python to your PATH. 25 | 26 | ##### **Linux: Debian-based** 27 | 28 | Most Debian-based systems come with Python pre-installed. Verify by running: 29 | 30 | ```shell 31 | python3 --version 32 | ``` 33 | 34 | If not installed, install it with: 35 | 36 | ```shell 37 | sudo apt-get update 38 | sudo apt-get install python3 python3-pip 39 | ``` 40 | 41 | ##### **Linux: Fedora** 42 | 43 | Fedora normally comes with Python pre-installed, to verify this, run: 44 | 45 | ```shell 46 | python3 --version 47 | ``` 48 | 49 | If Python is not installed on your system, you can install it like so: 50 | 51 | ```shell 52 | sudo dnf install python3 python3-pip 53 | ``` 54 | 55 | 56 | 57 | #### Python virtual environment 58 | 59 | 60 | 61 | ##### **Windows** 62 | 63 | Open a terminal window in your project directory. 64 | 65 | - *Open "Terminal" and navigate to the project directory 66 | `cd path/to/your/project/dir`* 67 | - *Alternatively, navigate to your project directory in File Explorer, 68 | then right-click in the empty space and select "Open in Terminal."* 69 | 70 | Create a virtual environment: 71 | 72 | ```shell 73 | python -m venv micropython-env 74 | ``` 75 | 76 | Activate the virtual environment: 77 | 78 | ```shell 79 | micropython-env\Scripts\activate 80 | ``` 81 | 82 | > [!NOTE] 83 | > In PowerShell, the activation command would be: 84 | > 85 | > ```ps 86 | > .\micropython-env\Scripts\Activate.ps1 87 | > ``` 88 | 89 | ##### **Linux: Debian-based** 90 | 91 | Install the `venv` module if it's not already installed: 92 | 93 | ```shell 94 | sudo apt-get install python3-venv 95 | ``` 96 | 97 | Create a virtual environment inside your project directory: 98 | 99 | ```shell 100 | python3 -m venv micropython-env 101 | ``` 102 | 103 | Activate the virtual environment: 104 | 105 | ```shell 106 | source micropython-env/bin/activate 107 | ``` 108 | 109 | ##### **Linux: Fedora** 110 | 111 | In Fedora, Python 3 includes the built-in venv module. 112 | 113 | Create a virtual environment inside your project directory: 114 | 115 | ```shell 116 | python3 -m venv micropython-env 117 | ``` 118 | 119 | Activate the virtual environment: 120 | 121 | ```shell 122 | source micropython-env/bin/activate 123 | ``` 124 | 125 | 126 | 127 | *Your terminal prompt should change to indicate that the virtual environment is active.* 128 | 129 | #### ESPTool 130 | 131 | [esptool](https://docs.espressif.com/projects/esptool/en/latest/esp32s3/index.html) 132 | is a Python-based tool that helps you flash the MicroPython firmware 133 | onto the ESP32-S3 SoC of your Walter board. Within the virtual environment, 134 | install esptool using pip: 135 | 136 | ```shell 137 | pip install esptool 138 | ``` 139 | 140 | #### Mpremote 141 | 142 | The MicroPython remote control CLI tool, [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html), 143 | provides a set of utilities for remotely interacting with a MicroPython device, 144 | managing its file system, and automating tasks over a serial connection. 145 | 146 | It can be installed using `pip` by running: 147 | 148 | ```console 149 | pip install --user mpremote 150 | ``` 151 | 152 | or via [pipx](https://pypa.github.io/pipx/) 153 | 154 | ```console 155 | pipx install mpremote 156 | ``` 157 | 158 | The simplest way to use it, is by simply typing `mpremote`. 159 | This will auto detect the first available USB serial device and access the REPL. 160 | It is highly recommended to read the 161 | [mpremote documentation](https://docs.micropython.org/en/latest/reference/mpremote.html) 162 | so you can make full use of it during your micropython development. 163 | 164 | > [!TIP] 165 | > If `mpremote` is not in your system's PATH, 166 | > you can run it by using `python -m mpremote` instead.\ 167 | > However, it is recommended to add it to your system's PATH 168 | > (if it did not automatically) should you intend on frequently using this tool. 169 | 170 | ### 2. Download MicroPython firmware 171 | 172 | Visit the [MicroPython ESP32-S3 download page](https://micropython.org/download/ESP32_GENERIC_S3/) 173 | and download the latest stable **.bin** firmware release for the ESP32-S3. 174 | 175 | ### 3. Identify the correct COM port 176 | 177 | 178 | 179 | #### **Windows** 180 | 181 | Connect your Walter to your computer via USB. Identify the COM port by opening 182 | Device Manager and checking under "Ports (COM & LPT)". 183 | The port will be labeled something like `COM3` or `COM4`. 184 | 185 | #### **Linux: Debian-based** 186 | 187 | Connect your ESP32-S3 to your computer via USB and identify the port by running: 188 | 189 | ```shell 190 | ls /dev/ttyACM* 191 | ``` 192 | 193 | #### **Linux: Fedora** 194 | 195 | Connect your ESP32-S3 to your computer via USB and identify the port by running: 196 | 197 | ```shell 198 | ls /dev/ttyACM* 199 | ``` 200 | 201 | 202 | The port will look something like `/dev/ttyACM0`, 203 | remember the port for the following steps. 204 | 205 | Alternatively, you can use `mpremote connect list` to get a list of all COM ports 206 | and anything connected on them. 207 | 208 | ### 4. Flash MicroPython onto the ESP32-S3 209 | 210 | 211 | 212 | #### **Windows** 213 | 214 | 1. **Erase the flash** Run the following command, 215 | replacing `` with your identified port from the previous step: 216 | 217 | ```shell 218 | esptool --chip esp32s3 --port erase_flash 219 | ``` 220 | 221 | 2. **Flash the firmware** Use esptool to flash the MicroPython firmware 222 | 3. onto the ESP32-S3. Replace `` and `` 223 | with your port and the path to the downloaded firmware: 224 | 225 | ```shell 226 | esptool --chip esp32s3 --port write_flash -z 0 227 | ``` 228 | 229 | #### **Linux: Debian-based** 230 | 231 | 1. **Erase the flash** Run the following command, 232 | replacing `` with your identified port from the previous step: 233 | 234 | ```shell 235 | esptool.py --chip esp32s3 --port erase_flash 236 | ``` 237 | 238 | 2. **Flash the firmware** Use esptool to flash the MicroPython firmware 239 | onto the ESP32-S3. Replace `` and `` 240 | with your port and the path to the downloaded firmware: 241 | 242 | ```shell 243 | esptool.py --chip esp32s3 --port write_flash -z 0 244 | ``` 245 | 246 | #### **Linux: Fedora** 247 | 248 | 1. **Erase the flash** Run the following command, 249 | replacing `` with your identified port from the previous step: 250 | 251 | ```shell 252 | esptool.py --chip esp32s3 --port erase_flash 253 | ``` 254 | 255 | 2. **Flash the firmware** Use esptool to flash the MicroPython firmware 256 | onto the ESP32-S3. Replace `` and `` 257 | with your port and the path to the downloaded firmware: 258 | 259 | ```shell 260 | esptool.py --chip esp32s3 --port write_flash -z 0 261 | ``` 262 | 263 | 264 | 265 | ### 5. Access the MicroPython REPL 266 | 267 | The REPL (Read-Eval-Print Loop) is an interactive prompt 268 | that allows you to run Python commands directly on the ESP32-S3. 269 | 270 | If only 1 device is connected, simply run: 271 | 272 | ```console 273 | mpremote 274 | ``` 275 | 276 | This will auto detect the first available USB serial device and access the REPL. 277 | Alternatively, specify the device using: 278 | 279 | ```console 280 | mpremote connect repl 281 | ``` 282 | 283 | If you wish not to use mpremote, see below alternative ways to access the REPL. 284 | 285 | 286 | 287 | #### **Windows** 288 | 289 | 1. **Install PuTTY**: Download and install PuTTY from the [official website](https://www.putty.org/). 290 | 291 | 2. **Open PuTTY**: 292 | - Set the connection type to `Serial`. 293 | - Enter your COM port (e.g., `COM3`) and set the speed to `115200`. 294 | - Click "Open" to start the session. 295 | 296 | 3. **Access the REPL**: Press the `Enter` key. 297 | You should see the MicroPython prompt (`>>>`). 298 | Try typing the following in the prompt: 299 | 300 | ```python 301 | >>> print('Hello Walter!') 302 | Hello Walter! 303 | ``` 304 | 305 | #### **Linux: Debian-based** 306 | 307 | 1. **Install picocom**: If you don't have picocom installed, install it using: 308 | 309 | ```shell 310 | sudo apt-get install picocom 311 | ``` 312 | 313 | 2. **Open a serial terminal**: Open picocom with the following command: 314 | 315 | ```shell 316 | picocom -b 115200 317 | ``` 318 | 319 | 3. **Access the REPL**: Press the `Enter` key. 320 | You should see the MicroPython prompt (`>>>`). 321 | Try typing the following in the prompt: 322 | 323 | ```python 324 | >>> print('Hello Walter!') 325 | Hello Walter! 326 | ``` 327 | 328 | #### **Linux: Fedora** 329 | 330 | 1. **Install picocom**: If you don't have picocom installed, install it using: 331 | 332 | ```shell 333 | sudo dnf install picocom 334 | ``` 335 | 336 | 2. **Open a serial terminal**: Open picocom with the following command: 337 | 338 | ```shell 339 | picocom -b 115200 340 | ``` 341 | 342 | 3. **Access the REPL**: Press the `Enter` key. 343 | You should see the MicroPython prompt (`>>>`). 344 | Try typing the following in the prompt: 345 | 346 | ```python 347 | >>> print('Hello Walter!') 348 | Hello Walter! 349 | ``` 350 | 351 | 352 | ### 6. Writing and running your first MicroPython script 353 | 354 | You can write and test simple scripts directly in the REPL, 355 | such as the following Hello World example: 356 | 357 | 1. **Hello World**: This simple script will print `Hello World` 358 | followed by a random int between 0 and 10 every second. 359 | Enter the following code in the REPL: 360 | 361 | ```python 362 | from time import sleep 363 | from random import randint 364 | 365 | while True: 366 | print("Hello World - %d" % randint(0, 10)) 367 | sleep(1) 368 | ``` 369 | 370 | 2. **Stopping the Script**: To stop the script, press `Ctrl+C`. 371 | 372 | ### 7. Uploading scripts 373 | 374 | Uploading files to a Walter running MicroPython lets you deploy full scripts 375 | that are saved to the device's filesystem, 376 | making them persistent and ready to run even after a reboot. 377 | Several tools are available, such as [Thonny](https://thonny.org/), 378 | [rshell](https://github.com/dhylands/rshell) and 379 | [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html). 380 | 381 | We recommend to use `mpremote`, as it is offered by micropython 382 | and is IDE independent.Read the 383 | [official mpremote documentation](https://docs.micropython.org/en/latest/reference/mpremote.html) 384 | to get a detailed overview and idea of what the tool has to offer. 385 | 386 | ### 8. Thonny 387 | 388 | For those who prefer a GUI to upload and communicate with the Micropython device, 389 | we recommend thonny. 390 | 391 | Thonny is an integrated development environment (IDE) designed for Python. 392 | It also supports MicroPython, making it a popular choice 393 | for uploading scripts to a MicroPython device. 394 | 395 | #### Install Thonny 396 | 397 | 398 | 399 | ##### **Windows** 400 | 401 | Download and install Thonny from the [official website](https://thonny.org/). 402 | 403 | ##### **Linux: Debian-based** 404 | 405 | Install Thonny using the following command: 406 | 407 | ```shell 408 | sudo apt-get install thonny 409 | ``` 410 | 411 | ##### **Linux: Fedora** 412 | 413 | Install Thonny using the following command: 414 | 415 | ```shell 416 | sudo dnf install thonny 417 | ``` 418 | 419 | 420 | #### Connect Thonny to ESP32-S3 421 | 422 | - Open Thonny and go to `Tools` > `Options` > `Interpreter`. 423 | - Set the interpreter to `MicroPython (ESP32)`. 424 | - Set the port to `< Try to detect port automatically >`. 425 | 426 | #### Write and upload scripts 427 | 428 | - Write your MicroPython script in the editor. 429 | - Click the `Run current script` button to run the script on Walter. 430 | 431 | ## Additional resources 432 | 433 | - [Official MicroPython Documentation](https://docs.micropython.org/en/latest/) 434 | - [mpremote Documentation](https://docs.micropython.org/en/latest/reference/mpremote.html) 435 | - [Esptool.py Documentation](https://docs.espressif.com/projects/esptool/en/latest/esp32s3/index.html) 436 | - [Thonny IDE](https://thonny.org/) 437 | -------------------------------------------------------------------------------- /developer-toolchains/toit.md: -------------------------------------------------------------------------------- 1 | ## Prerequisites 2 | 3 | We assume that you have set up your development environment as described in 4 | [the IDE tutorial](https://docs.toit.io/tutorials/setup/ide) 5 | 6 | We also assume that you have flashed your device with Jaguar and that you are 7 | familiar with running Toit programs on it. If not, have a look at the 8 | [Hello world](https://docs.toit.io/tutorials/setup/firstprogram) tutorial. 9 | 10 | Note that the Walter device is an ESP32-S3 board, which requires the 11 | `--chip=esp32s3` flag when flashing. 12 | 13 | In later sections we will refer to containers and services, but these are not 14 | strictly necessary. 15 | 16 | We will use HTTP to fetch data from the internet. 17 | 18 | ## Packages 19 | 20 | Cellular functionality is not part of the core libraries and must be imported as 21 | a package. See the [packages](https://docs.toit.io/tutorials/setup/packages) 22 | tutorial for details. 23 | 24 | As of writing, all drivers for cellular modems are in the 25 | [cellular](https://pkg.toit.io/package/github.com%2Ftoitware%2Fcellular@v2) package. 26 | 27 | To install it, run the following command: 28 | 29 | ```toit 30 | jag pkg install github.com/toitware/cellular@v2 31 | ``` 32 | 33 | We will use the 34 | [http](https://pkg.toit.io/package/github.com%2Ftoitlang%2Fpkg-http@v2) and the 35 | [certificate-roots](https://pkg.toit.io/package/github.com%2Ftoitware%2Ftoit-cert-roots@v1) 36 | packages to fetch data from the internet. 37 | 38 | ```toit 39 | jag pkg install github.com/toitlang/pkg-http@v2 40 | jag pkg install github.com/toitware/toit-cert-roots@v1 41 | ``` 42 | 43 | ## Code 44 | 45 | Start a new Toit program `walter.toit` and watch it with Jaguar. If necessary, 46 | uncomment the `CONFIG-APN` line and set the correct APN for your provider. 47 | 48 | ```toit 49 | import cellular.modules.sequans.monarch 50 | import http 51 | import encoding.json 52 | import net 53 | import net.cellular 54 | import certificate-roots 55 | ​ 56 | RX ::= 14 57 | TX ::= 48 58 | RTS ::= 21 59 | CTS ::= 47 60 | RESET ::= 45 61 | POWER ::= 46 62 | BAUD ::= 115200 63 | ​ 64 | main: 65 | // Start the monarch driver/provider. 66 | task --background:: 67 | monarch.main 68 | ​ 69 | // Establish the connection to the network. 70 | network := cellular.open --name="gm02sp" { 71 | cellular.CONFIG-UART-RX: RX, 72 | cellular.CONFIG-UART-TX: TX, 73 | cellular.CONFIG-UART-CTS: CTS, 74 | cellular.CONFIG-UART-RTS: RTS, 75 | cellular.CONFIG-RESET: [RESET, cellular.CONFIG-ACTIVE-LOW], 76 | cellular.CONFIG-POWER: POWER, 77 | cellular.CONFIG-UART-BAUD-RATE: BAUD, 78 | // If your provider requires an APN, you can set it here. 79 | // cellular.CONFIG-APN: "", 80 | } 81 | ​ 82 | try: 83 | do-network-things network 84 | finally: 85 | network.close 86 | ``` 87 | 88 | Even though the modem isn't a "Monarch", but a "GM02SP", we can use the monarch 89 | driver. Both are manufactured by Sequans, and use similar AT commands. 90 | Eventually, there might be a more specialized driver for the GM02SP. 91 | 92 | The `monarch.main` function installs the driver as a provider so that other code 93 | can use it through a service. We happen to use it from the same process, but 94 | that's not a requirement. In fact, we will see later how the provider can be 95 | started in a different container, so that different programs can have access to 96 | the internet at the same time. 97 | 98 | Once the provider is running in the background, we simply use the 99 | `cellular.open` function to establish a connection to the network. It will 100 | return a `net.Client` object that we can pass to code that needs to use the 101 | network. 102 | 103 | For example, the `do-network-things` function could look as follows: 104 | 105 | ```toit 106 | do-network-things network/net.Client: 107 | certificate-roots.install-common-trusted-roots 108 | client := http.Client.tls network 109 | request := client.get --uri="https://official-joke-api.appspot.com/random_joke" 110 | decoded := json.decode-stream request.body 111 | print decoded["setup"] 112 | print decoded["punchline"] 113 | ``` 114 | 115 | ## Container 116 | 117 | In our first iteration the cellular provider was started in the same container 118 | as the rest of the code. This is not ideal, as the cellular connection is then 119 | not available to other containers. 120 | 121 | We can fix this, by installing the cellular provider in its own container. 122 | 123 | Create a new file `cellular.toit` with the following content. If necessary, 124 | uncomment the `CONFIG-APN` line and set the correct APN for your provider. 125 | 126 | ```toit 127 | import net.cellular 128 | import cellular.modules.sequans.monarch 129 | ​ 130 | RX ::= 14 131 | TX ::= 48 132 | RTS ::= 21 133 | CTS ::= 47 134 | RESET ::= 45 135 | POWER ::= 46 136 | BAUD ::= 115200 137 | ​ 138 | class WalterCellularProvider extends monarch.MonarchService: 139 | connect client/int config/Map? -> List: 140 | if not config or config.is-empty: 141 | config = { 142 | cellular.CONFIG-UART-RX: RX, 143 | cellular.CONFIG-UART-TX: TX, 144 | cellular.CONFIG-UART-CTS: CTS, 145 | cellular.CONFIG-UART-RTS: RTS, 146 | cellular.CONFIG-RESET: [RESET, cellular.CONFIG-ACTIVE-LOW], 147 | cellular.CONFIG-POWER: POWER, 148 | cellular.CONFIG-UART-BAUD-RATE: BAUD, 149 | // If your provider requires an APN, you can set it here. 150 | // cellular.CONFIG-APN: "", 151 | } 152 | return super client config 153 | ​ 154 | main: 155 | provider := WalterCellularProvider 156 | provider.install 157 | ``` 158 | 159 | The `WalterCellularProvider` extends the `MonarchService` (which was installed 160 | as part of the `monarch.main` call in the previous section), and overrides the 161 | connect method to use the constants for the Walter board. 162 | 163 | Note that the name `MonarchService` is a bit misleading, as it is actually a 164 | provider (extending the `CellularServiceProvider` class). 165 | 166 | The `main` function then installs the provider, so that containers can use it. 167 | 168 | We can now install this container on the device: 169 | 170 | ```toit 171 | jag container install cellular cellular.toit 172 | ``` 173 | 174 | Other containers can now use the cellular provider. 175 | 176 | For example, create, and watch the following `cellular-user.toit` program: 177 | 178 | ```toit 179 | import net 180 | import net.cellular 181 | ​ 182 | do-network-things network/net.Client: 183 | ... 184 | ​ 185 | main: 186 | network := cellular.open --name="walter" {:} 187 | ​ 188 | try: 189 | do-network-things network 190 | finally: 191 | network.close 192 | ``` 193 | 194 | The `do-network-things` function could be the same as in the previous section 195 | (in which case you will have to add a few more imports). 196 | 197 | Note that multiple containers can call `cellular.open` at the same time and 198 | access the internet concurrently. 199 | -------------------------------------------------------------------------------- /developer-toolchains/zephyr.md: -------------------------------------------------------------------------------- 1 | ## TL;DR 2 | 3 | ## History 4 | 5 | The DPTechnics team started by contributing support for the Sequans GM02S(P), 6 | this was merged on the 6th of May, 2024 in 7 | [pull request #72217](https://github.com/zephyrproject-rtos/zephyr/pull/72217). 8 | 9 | Official board support for Walter was added in 10 | [pull request #73351](https://github.com/zephyrproject-rtos/zephyr/pull/73351) 11 | on the 17th of September, 2024. 12 | -------------------------------------------------------------------------------- /faq/communication.md: -------------------------------------------------------------------------------- 1 | ## Communication 2 | 3 | ### Does Walter support both LTE-M and NB-IoT? 4 | 5 | Yes, Walter supports both LTE-M and NB-IoT. 6 | You can force the RAT *(Radio Access Technology)* using: 7 | 8 | ```cpp 9 | modem.setRAT(WALTER_MODEM_RAT_LTEM) // for LTE-M 10 | modem.setRAT(WALTER_MODEM_RAT_NBIOT) // for NB-IoT 11 | ``` 12 | 13 | Followed by `modem.reset()`. 14 | 15 | ### What protocols are supported? 16 | 17 | Walter supports: 18 | 19 | - CoAP + DTLS *(recommended for low data usage as it's UDP-based)* 20 | - MQTT/MQTTS 21 | - HTTP/HTTPS 22 | - Raw UDP 23 | - Raw TCP 24 | 25 | ### Can I force Walter to connect to a specific network? 26 | 27 | Yes, you can manually set the network using AT commands. 28 | Example for Vodafone UK: 29 | 30 | ```console 31 | AT+SQNMODEACTIVE=2 32 | AT^RESET 33 | AT+CGDCONT=1,"IP","soracom.io" 34 | AT+CFUN=1 35 | AT+CGATT=0 36 | AT+COPS=1,2,"23415" 37 | ``` 38 | 39 | ### Should I use MQTT or CoAP? 40 | 41 | CoAP is recommended over MQTT for lower data usage 42 | as it's UDP-based instead of TCP-based. 43 | If you are using NB-IoT you should not use TCP-based protocols. 44 | As this might sometimes work it is not guaranteed 45 | and will give bad results when you scale up. 46 | 47 | ### What should I do if I get CME ERROR 4? 48 | 49 | CME ERROR 4 typically indicates a network-related issue. Common solutions: 50 | 51 | 1. Check if you're in an area with good coverage 52 | 2. Verify your SIM card is properly provisioned 53 | 3. Consider using an external antenna in areas with poor reception 54 | 4. Implement automatic reconnection logic in your code 55 | 5. Avoid reconnecting more than 3-6 times per hour to prevent network rejection 56 | -------------------------------------------------------------------------------- /faq/gnss-gps.md: -------------------------------------------------------------------------------- 1 | ## GNSS/GPS 2 | 3 | ### Which GNSS antenna should I use? 4 | 5 | The recommended antenna is the passive Taoglas FXP.611. 6 | Active antennas are not supported by the board. 7 | 8 | ### How sensitive is the built-in GNSS? 9 | 10 | The Walter board's GNSS sensitivity varies by start condition: 11 | 12 | - Cold start *(no valid assistance)*: -146dBm 13 | - Warm start *(valid assistance, no position)*: -150.5dBm 14 | - Hot start *(valid assistance, position within 100km)*: -153.3dBm 15 | 16 | ### Why can't I get a GNSS fix indoors? 17 | 18 | GNSS is not suited for indoor positioning, even with dedicated modules. 19 | While you might get a signal indoors, 20 | it will likely be noisy with degraded accuracy. 21 | Indoor reception is limited due to: 22 | 23 | - Building materials blocking signals 24 | - Window coatings (especially silver/metallic) interfering with reception 25 | - Lower sensitivity compared to dedicated GNSS modules 26 | 27 | For indoor applications, consider alternative positioning technologies such as 28 | Bluetooth beacons or WiFi scanning. Both are supported by Walter. 29 | -------------------------------------------------------------------------------- /faq/hardware-features.md: -------------------------------------------------------------------------------- 1 | ## Hardware Features 2 | 3 | ### How do I enable the 3.3V output? 4 | 5 | The 3V3 OUT (pin 26) is software controllable and the output is not enabled by 6 | default. You need to enable the 3.3V in your code: 7 | 8 | - Set GPIO0 LOW to enable 3.3V output 9 | - Set GPIO0 HIGH to disable 3.3V output 10 | 11 | ### Does Walter support CAN bus? 12 | 13 | Yes, but it requires an external CAN transceiver *(e.g., SN65HVD232)* 14 | to convert TTL levels to CAN bus levels. 15 | The ESP32-S3's built-in TWAI peripheral is used for CAN communication. 16 | 17 | ### Can Walter monitor input voltage? 18 | 19 | Yes, you can monitor the VIN voltage using the AT+SQNVMON command. 20 | The Sequans modem is directly connected to VIN, 21 | while the ESP32-S3 uses a DC-DC converter for stable 3.3V. 22 | -------------------------------------------------------------------------------- /faq/modem-update.md: -------------------------------------------------------------------------------- 1 | ## Modem update 2 | 3 | ### How can I see the Sequans GM02SP firmware version 4 | 5 | First flash the [modem passthrough](https://github.com/QuickSpot/walter-arduino/tree/main/examples/ModemPassthrough) 6 | example onto Walter to get direct access to the AT command interface of the modem. You can now 7 | issue the following commands: 8 | - `ATI1`: to get the firmware revision of the modem 9 | - `ATI3`: to get the hardware revision of the modem 10 | 11 | ### How can I update the Sequans GM02SP firmware 12 | 13 | The latest official firmware version is **LR8.2.1.0-61488**. This release includes significant improvements in **NB-IoT performance**. The first step in the upgrade process is to flash the [modem passthrough](https://github.com/QuickSpot/walter-arduino/tree/main/examples/ModemPassthrough) example onto Walter to get direct access to the AT command interface of the modem. 14 | 15 | Now use the `ATI1` command to make sure that the modem is currently running version **LR8.2.0.3-60186**. You cannot 16 | use the below update method starting from other firmware versions. 17 | 18 | > [!WARNING] 19 | > The upgrade **resets hardware configurations** such as UART speed and wake source settings. Ensure that you follow > the instructions below to preserve or restore these settings. 20 | 21 | > [!note] 22 | > The update can take a long time. Depending on the network connection it can take between 10 and 30 minutes 23 | > to complete, please do not power-cycle the modem. 24 | 25 | Follow these steps to perform the FOTA upgrade: 26 | 1. **Avoid a power cut** during the upgrade process (the modem can recover from it, but uninterrupted power is recommended). 27 | 2. **Create a factory restore point**: 28 | ```bash 29 | AT+CFUN=5 30 | AT+SQNFACTORYSAVE="quickspot" 31 | ``` 32 | 3. **Enable security configuration**: 33 | ```bash 34 | AT+SQNSPCFG=1,2 35 | ``` 36 | 37 | 4. **Enable full functionality**: 38 | ```bash 39 | AT+CFUN=1 40 | ``` 41 | 42 | 5. **Initiate upgrade** after you received CEREG 1 or 5: 43 | ```bash 44 | AT+SQNSUPGRADE="https://quickspot.io/firmware/GP02RBAQ-DM_LR8.2.0.3-60186_to_LR8.2.1.0-61488_Bootrom.dup",1,10,1,1 45 | ``` 46 | 6. **Factory reset the HW config**: 47 | ```bash 48 | AT+SQNSFACTORYRESET 49 | ``` -------------------------------------------------------------------------------- /faq/power-management.md: -------------------------------------------------------------------------------- 1 | ## Power Management 2 | 3 | ### How do I implement sleep mode in Walter? 4 | 5 | The modem automatically enters its lowest power mode when: 6 | 7 | 1. It's disconnected from the network using 8 | `setOpState(WALTER_MODEM_OPSTATE_MINIMUM)` 9 | 2. It finishes a transmission and enters RRC idle mode with PSM or eDRX enabled 10 | 11 | Example code for configuring power saving: 12 | 13 | ```cpp 14 | // Enable PSM (Power Saving Mode) 15 | modem.configPSM(WALTER_MODEM_PSM_ENABLE,"01101011", "00101010"); 16 | 17 | // or configure eDRX 18 | modem.configEDRX(); 19 | ``` 20 | 21 | ### What happens when ESP32 goes into deep sleep? 22 | 23 | When configuring PSM using 24 | `configPSM(WALTER_MODEM_PSM_ENABLE, "01101011", "00101010")`, 25 | the modem will automatically enter sleep mode when the conditions are met. 26 | You don't need to explicitly disconnect from the network. 27 | The `configPSM()` function only configures the behavior 28 | and doesn't immediately trigger sleep mode. 29 | -------------------------------------------------------------------------------- /faq/software-development.md: -------------------------------------------------------------------------------- 1 | ## Software Development 2 | 3 | ### Are there OTA (Over-The-Air) update options? 4 | 5 | Yes, there are several options for OTA updates: 6 | 7 | - Using BlueCherry's OTA system with CoAP + DTLS 8 | - Using ESP-IDF's built-in OTA functionality 9 | - Using Zephyr's OTA capabilities 10 | - Custom implementation using CoAP or other protocols 11 | 12 | ### How do I get the current time? 13 | 14 | After establishing an LTE connection, 15 | you can get the network time using the modem's getClock() function: 16 | 17 | ```cpp 18 | if(modem.getClock(&rsp)) { 19 | if(rsp.data.clock > 0) { 20 | // rsp.data.clock contains UTC timestamp 21 | } 22 | } 23 | ``` 24 | 25 | ### Is the WalterModem library thread-safe? 26 | 27 | No, thread locking is not implemented in the library 28 | and is left to the application level. 29 | 30 | ### Where can I find example code? 31 | 32 | Examples can be found in: 33 | 34 | - GitHub repository 35 | () 36 | - QuickSpot documentation 37 | () 38 | 39 | ### How do I enable debugging? 40 | 41 | You can enable debug output in the Arduino IDE under Tools menu 42 | by setting the debug level to 'DEBUG'. 43 | This will show more detailed output including AT commands. 44 | -------------------------------------------------------------------------------- /faq/troubleshooting.md: -------------------------------------------------------------------------------- 1 | ## Troubleshooting 2 | 3 | ### I'm unable to flash Walter. How do I force the module into flash mode? 4 | 5 | Walter utilizes the ESP32-S3's built-in USB-to-serial peripheral. 6 | However, if the chip has been flashed with software 7 | that disables this functionality or if the firmware is stuck 8 | in a high-frequency boot loop, you may encounter issues 9 | when attempting to flash the Walter module. 10 | 11 | To resolve this, you can force Walter into flashing mode 12 | by pulling `GPIO0` to ground before powering it on. 13 | This will prevent the chip from booting its current firmware, 14 | allowing it to remain in a waiting state 15 | for new firmware to be downloaded over USB-C or serial. 16 | 17 | ### Why does Walter keep restarting? 18 | 19 | Common causes include: 20 | 21 | 1. Insufficient power supply 22 | - ensure stable power through USB-C or external power 23 | 2. Network connectivity issues 24 | - implement proper error handling 25 | 3. Memory issues 26 | - check for memory leaks in your application 27 | 4. Buffer overflows 28 | - particularly in areas with poor signal strength 29 | 30 | ### How do I enable debug logging? 31 | 32 | Set the Arduino IDE debug level to "Debug" in board settings, or in code: 33 | 34 | ```cpp 35 | modem.setDebug(true); 36 | ``` 37 | 38 | ### Serial Monitor issues with sleep mode? 39 | 40 | The Arduino IDE serial monitor may not reconnect properly after sleep mode. 41 | This is due to the fact that Walter uses the USB-Serial hardware 42 | that is built-in into the ESP32-S3, 43 | this converter is powered off in deep sleep which effectively 44 | disconnects the Walter module from the host computer during deep sleep. 45 | Not all software can handle this correctly, possible solutions are: 46 | 47 | 1. Use Visual Studio Code with the 48 | [Serial Monitor extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-serial-monitor) 49 | 2. Use an external USB-to-UART converter 50 | -------------------------------------------------------------------------------- /file/gm02s_at_commands.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/file/gm02s_at_commands.pdf -------------------------------------------------------------------------------- /guides/cellular_connectivity.md: -------------------------------------------------------------------------------- 1 | ## TL;DR; 2 | 3 | Walter's modem supports two cellular technologies: 4 | 5 | - LTE Cat-M1 or LTE-M 6 | - LTE Cat-NB1/NB2 or NB-IoT 7 | 8 | Both technologies were introduced in 4G with 3GPP rel. 13 and belong to the 9 | LPWAN (*Long Range Wide Area Network*) family of protocols. These protocols are 10 | designed to consume little power and have a long range. Very important is that 11 | both of these cellular protocols are also available in 5G which ensures that 12 | Walter is going to be able to connect when providers switch of their 4G 13 | infrastructure. 14 | 15 | Many 'consumer' SIM cards do not offer access to these cellular IoT networks and 16 | it is therefore important for you to check if your SIM card supports LTE-M or 17 | NB-IoT. 18 | 19 | ## No SIM card lock 20 | 21 | Walter is absolutely SIM lock free. This means that you get absolute freedom 22 | over which provider you are using. 23 | 24 | ## The Soracom SIM card 25 | 26 | DPTechnics has teamed up with Soracom to be able to provide anyone, also private 27 | individuals, with an IoT SIM card that supports both LTE Cat-M1 and LTE 28 | Cat-NB1/NB2. The SIM cards can be ordered via the 29 | [DPTechnics web shop](https://shop.dptechnics.com/). 30 | 31 | Before choosing a SIM card it is important to check coverage as roaming 32 | agreements for cellular IoT is still an ongoing process, especially NB-IoT 33 | roaming is still in development. As the availability gets better every day, 34 | Soracom keeps track of coverage with eDRX and PSM availability in a 35 | [Github repository](https://github.com/soracom/coverage-tests/blob/main/SORACOM-LPWAN-with-features.csv). 36 | 37 | > We have received feedback from UK users with a Soracom card that LTE-M 38 | > coverage has not been very good. Therefore we advice to stick to NB-IoT 39 | > in the UK. 40 | 41 | ## Other tested SIM cards 42 | 43 | Our customers have tested Walter with a variety of SIM cards that might also 44 | be interesting for your business case. People have reported success with the 45 | following SIM card providers: 46 | 47 | - [1NCE](https://1nce.com/): known for their 10EUR/10Years cards 48 | - [Vodaphone](https://www.vodafone.com/business/products/iot-connectivity): 49 | an MNO with a global presence 50 | - [SIM control](https://simcontrol.co.za/): NB-IoT in South Africa 51 | - [Telenet](https://www2.telenet.be/business/nl/sme-le/aanbod/verbinden/bedrijfsnetwerk/internet-of-things.html): 52 | Belgium NB-IoT 53 | 54 | There are definitely many other SIM cards/vendors that will work and this is one 55 | of the biggest advantages of cellular IoT. You have a choice. 56 | 57 | ## Consumer cards that support LTE-M 58 | 59 | In 3GPP release 13 it is not possible for providers to check if an incoming 60 | connection is LTE Cat-M1 or another version (cat 1bis, cat 1, cat 4, ...). The 61 | MNO (*Mobile Network Operator*) can only see this after the device has 62 | connected. It is therefore sometimes possible to connect to LTE-M using a normal 63 | SIM card although some providers also allow NB-IoT connectivity. Based on tests 64 | done by users of Walter we have confirmed that the following cards are working: 65 | 66 | | Country | Provider | Radio Access Technology | 67 | |:-------------------:|:----------------:|:-----------------------:| 68 | | Belgium | Orange | LTE-M | 69 | | Belgium | Hey! | LTE-M | 70 | | Swiss Confederation | Digital Republic | LTE-M | 71 | | Australia | Telstra Prepaid | NB-IoT | 72 | | Finland | Elisa Prepaid | LTE-M | 73 | 74 | Please note than in the above cases eDRX and PSM are almost never available. 75 | -------------------------------------------------------------------------------- /guides/getting_started.md: -------------------------------------------------------------------------------- 1 | ## TL;DR 2 | 3 | 1. Insert the SIM card. 4 | 2. Connect the LTE antenna, **mandatory** when using LTE. 5 | 3. Connect GNSS antenna, Walter requires a passive GNSS antenna. 6 | 4. Make sure Walter and/or the GNSS antenna has a clear view to the sky. 7 | 5. Power up Walter via the USB-C connection. 8 | 6. Browse to [walterdemo.quickspot.io](https://walterdemo.quickspot.io/). 9 | 7. As soon as a GNSS position could be determined or after 7 minutes without 10 | GNSS reception you should see your Walter appearing on the portal. You can 11 | recognize your Walter by his MAC address. 12 | 13 | ![SIM card insertion](img/getting_started_walter_sim_insert.jpg) 14 | 15 | ## Prepare the hardware 16 | 17 | Walter comes with a broad range on connectivity options. If you only want to use 18 | the WiFi and Bluetooth connection offered by the ESP32-S3 there is no need to 19 | connect any antenna's. 20 | 21 | When you also want to make use of the LTE radio it is **mandatory** to connect 22 | an LTE antenna, failing to do so may irreversibly destroy the RF frontend of the 23 | modem. Walter recommends the following antennas: 24 | 25 | - LTE: [Taoglas FXUB63.07.0150C](https://www.taoglas.com/product/fxub63-ultra-wide-band-flex-antenna/) 26 | - GNSS: [Taoglas FXP611.07.0092C](https://www.taoglas.com/product/cloud-fxp611-gps-glonass-compass-flexible-pcb-2/) 27 | 28 | > [!note] 29 | > Walter only works with passive GNSS antennas as there is no phantom 30 | > power on the GNSS antenna connector. The LNA and SAW filter are integrated on 31 | > the Walter module. If you would connect an active antenna you will not get a 32 | > fix. 33 | 34 | To power up Walter you can use a standard USB-C cable and connect Walter to your 35 | PC or a power bank. You can also power Walter via the header pins (Vin and GND). 36 | 37 | > [!WARNING] 38 | > The USB-C power and Vin pin are internally connected. If you are 39 | > powering Walter through the headers pins it is best to use an USB-C cable of 40 | > which the VCC wire has been cut. 41 | 42 | ## The pre-flashed firmware 43 | 44 | Every Walter comes pre-flashed with an example application which requires you 45 | to connect the LTE and GNSS antennas. The out-of-the box firmware performs the 46 | following tasks: 47 | 48 | 1. Configure the modem for LTE-M connectivity with network pushed APN. 49 | 2. Check and update GNSS assistance data if required. 50 | 3. Try to establish a GNSS fix, the firmware will try this up to 5 times and 51 | the maximum duration of an attempt is approximately 66 seconds. 52 | 4. Upload the data to the 53 | [walterdemo.quickspot.io](https://walterdemo.quickspot.io/) portal. 54 | 55 | To make use of this pre-flashed demonstrator you should 56 | [prepare the hardware](#prepare-the-hardware) by installing LTE and GNSS 57 | antenna. Also insert a SIM card which supports LTE-M. You can now power up 58 | Walter and give him some time to send out his first message. Make sure the GNSS 59 | antenna has a clear view to the sky and allow Walter about 10 minutes to connect 60 | and upload the first data. 61 | 62 | On the [walterdemo.quickspot.io](https://walterdemo.quickspot.io/) portal you 63 | can see all Walter boards which have ever sent data to the demonstration portal. 64 | Every Walter identifies itself using his MAC address which is printed on the bag 65 | in which you received your Walter board. 66 | 67 | In case you lost the bag you can also watch to the console output from Walter to 68 | discover it's MAC address. To see console output you must connect Walter to 69 | your computer using the built-in USB-C port. After plugging in Walter you should 70 | get a serial port: 71 | 72 | - On Windows: COMxx 73 | - On Linux or macOS: /dev/tty* 74 | 75 | The serial console of the demonstration application runs with 115200 baud. On 76 | Windows you can use a simple program such as 77 | [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) to view 78 | the console and on Linux or macOS you can just use the `cat` command. After 79 | opening the serial port you should see the MAC address of your Walter board in 80 | the following format: 81 | 82 | ```console 83 | Walter Positioning v0.0.2 84 | Walter's MAC is: 48:27:E2:10:DF:30 85 | ``` 86 | -------------------------------------------------------------------------------- /guides/guides.md: -------------------------------------------------------------------------------- 1 | ## Guides 2 | 3 | - [Getting Started](/guides/getting_started.md) 4 | - [Cellular Connectivity](/guides/cellular_connectivity.md) 5 | -------------------------------------------------------------------------------- /guides/img/getting_started_walter_sim_insert.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/guides/img/getting_started_walter_sim_insert.jpg -------------------------------------------------------------------------------- /hardware/hardware.md: -------------------------------------------------------------------------------- 1 | ## Hardware 2 | 3 | - [Walter](/hardware/walter.md) 4 | - [Walter Feels](/hardware/walter_feels.md) 5 | -------------------------------------------------------------------------------- /hardware/img/walter-feels-transparent-01.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/hardware/img/walter-feels-transparent-01.png -------------------------------------------------------------------------------- /hardware/walter.md: -------------------------------------------------------------------------------- 1 | ## Module overview 2 | 3 | ![drawing](img/walter-functionality-numbered-stroke.svg) 4 | 5 | The Walter module has the following components: 6 | 7 | 1. 5G LPWAN modem & GNSS receiver 8 | 2. Reset button 9 | 3. USB Type-C connector for power and programming 10 | 4. 5G antenna connector 11 | 5. GNSS antenna connector (**passive antenna only**) 12 | 6. Integrated GNSS LNA + SAW filter 13 | 7. 3.3V output switch 14 | 8. Ultra low quiescent current DC-DC converter 15 | 9. ESP32-S3 SoC with 16MiB flash and 2MiB PSRAM 16 | 10. Wi-Fi and BLE antenna 17 | 11. 2.54mm pin headers, breadboard friendly 18 | 12. Test pads 19 | 13. Nano SIM card slot 20 | 21 | ## Intended use 22 | 23 | Walter is a small-form-factor IoT system-on-module (SoM) that combines a 24 | powerful 25 | [Espressif ESP32-S3](https://www.espressif.com/en/products/socs/esp32-s3) 26 | system-on-chip (SoC) with a second-generation 27 | [Sequans GM02SP](https://sequans.com/products/monarch-2-gm02sp/) 28 | LTE-M/NB-IoT 5G modem and GNSS receiver. Its ESP32-S3 provides many built-in 29 | peripherals as well, including UART, SPI, I²C, CAN, Wi-Fi b/g/n, and 30 | Bluetooth 5. Walter is the only module that packs all of these connectivity 31 | options into such a small package. While ideal for prototyping you can also use 32 | Walter for production as it is fully certified (CE, UKCA, FCC, IC, RCM). 33 | 34 | ## Power 35 | 36 | ### Power input 37 | 38 | Walter can be powered either by connecting a USB-C cable or via the VIN pin. 39 | The module accepts any input voltage between 3.0V and 5.5V. 40 | 41 | > **DO NOT** power Walter with both the USB-C connection and the VIN-pin! This 42 | > can lead to seriously damaging the board and external peripherals connected to 43 | > it! To minimize losses the USB-C power input and Vin input pin are directly 44 | > connected to each other. If you want to debug your application through USB-C 45 | > while Walter is plugged into a carrier board we advise you to modify a USB-C 46 | > cable by cutting the power lead. 47 | 48 | ### 3.3V output 49 | 50 | Walter contains a Texas Instruments TPS6208833 DC-DC Converter which takes power 51 | from either the USB-C port or the VIN-pin and converts it to a regulated +3.3VDC 52 | supply. The maximum load on the 3.3VDC output is 250mA. 53 | 54 | ## Pinout 55 | 56 | ![drawing](img/hardware_pinout.svg) 57 | 58 | ## Pin descriptions 59 | 60 | | Pin | Function | ESP pin | Input/Output | ADC | RTC | Touch | Description | 61 | |:---:|:----------:|:-------:|---------------|----------|-----|---------|--------------------------------------------| 62 | | 1 | RESET | EN | input | No | No | No | ESP32-S3 reset with 10k pull-up | 63 | | 2 | IO44/RX0 | RXD0 | bidirectional | No | No | No | ESP32-S3 UART0 receive | 64 | | 3 | IO43/TX0 | TXD0 | bidirectional | No | No | No | ESP32-S3 UART0 transmit | 65 | | 4 | DFU/3V3_EN | IO0 | bidirectional | No | Yes | No | DFU when low on boot and 3V3 output enable | 66 | | 5 | IO12 | IO12 | bidirectional | ADC2_CH1 | Yes | TOUCH12 | General purpose I/O port | 67 | | 6 | IO11 | IO11 | bidirectional | ADC2_CH0 | Yes | TOUCH11 | General purpose I/O port | 68 | | 7 | IO13 | IO13 | bidirectional | ADC2_CH2 | Yes | TOUCH13 | General purpose I/O port | 69 | | 8 | IO38 | IO38 | bidirectional | No | No | No | General purpose I/O port | 70 | | 9 | IO39 | IO39 | bidirectional | No | No | No | General purpose I/O port | 71 | | 10 | IO40 | IO40 | bidirectional | No | No | No | General purpose I/O port | 72 | | 11 | IO41 | IO41 | bidirectional | No | No | No | General purpose I/O port | 73 | | 12 | IO42 | IO42 | bidirectional | No | No | No | General purpose I/O port | 74 | | 13 | IO2 | IO2 | bidirectional | ADC1_CH1 | Yes | TOUCH2 | General purpose I/O port | 75 | | 14 | IO1 | IO1 | bidirectional | ADC1_CH0 | Yes | TOUCH1 | General purpose I/O port | 76 | | 15 | IO4 | IO4 | bidirectional | ADC1_CH3 | Yes | TOUCH4 | General purpose I/O port | 77 | | 16 | IO5 | IO5 | bidirectional | ADC1_CH4 | Yes | TOUCH5 | General purpose I/O port | 78 | | 17 | IO6 | IO6 | bidirectional | ADC1_CH5 | Yes | TOUCH6 | General purpose I/O port | 79 | | 18 | IO7 | IO7 | bidirectional | ADC1_CH6 | Yes | TOUCH7 | General purpose I/O port | 80 | | 19 | IO15 | IO15 | bidirectional | ADC2_CH4 | Yes | No | General purpose I/O port | 81 | | 20 | IO16 | IO16 | bidirectional | ADC2_CH5 | Yes | No | General purpose I/O port | 82 | | 21 | IO17 | IO17 | bidirectional | ADC2_CH6 | Yes | No | General purpose I/O port | 83 | | 22 | IO18 | IO18 | bidirectional | ADC2_CH7 | Yes | No | General purpose I/O port | 84 | | 23 | IO8 | IO8 | bidirectional | ADC1_CH7 | Yes | TOUCH8 | General purpose I/O port | 85 | | 24 | IO9 | IO9 | bidirectional | ADC1_CH8 | Yes | TOUCH9 | General purpose I/O port | 86 | | 25 | IO10 | IO10 | bidirectional | ADC1_CH9 | Yes | TOUCH10 | General purpose I/O port | 87 | | 26 | 3V3 OUT | N/A | power output | No | No | No | General purpose I/O port | 88 | | 27 | GND | GND | power ground | No | No | No | GND connection | 89 | | 28 | VIN | N/A | power input | No | No | No | 3.0 - 5V power input port | 90 | 91 | > The pins on Walter are designed to work in the 3.3V domain. If you want to 92 | > connect 5V peripherals you must use a suitable level translation technique. 93 | 94 | ## Special functions and IO mux 95 | 96 | One of the advantages of the ESP32-S3 in comparison to the older ESP32 is that 97 | the pin multiplexer functionality has been significantly expanded. It is 98 | therefore possible to select any of the normal I/O pins for any digital 99 | peripheral. If you want to process analog signals with any of the two built-in 100 | ADCs you need to take into account the following limitations: 101 | 102 | - ADC1 can use IO pins 1, 2, 4, 5, 6, 7, 8, 9, 10 103 | - ADC2 can use IO pins 11, 12, 13, 15, 16, 17, 18 104 | 105 | > [!note] 106 | > The ADC2 peripheral is used by the ESP32-S3 if WiFi is enabled. 107 | > While you can still use ADC2 with WiFi enabled it can fail as the WiFi radio has 108 | > prioritized access to the ADC2 peripheral. We therefore recommend not to use 109 | > ADC2 simultaneously with WiFi. 110 | 111 | The ESP32-S3 has an ultra low power (ULP) 112 | [RISC-V](https://en.wikipedia.org/wiki/RISC-V) 113 | co-processor which can operate during deep-sleep. This co-processor can control 114 | IO pins which are in the RTC domain. In the case of Walter the available RTC 115 | IO pins are 0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18. 116 | 117 | IO0 is a 'strapping pin' which means that the state of the pin at boot 118 | determines module configuration. In case of IO0 there are two options described 119 | in the below table. Once the application has booted the application uses IO0 to 120 | switch on or off the 3.3V output pin in an active-low fashion. This means that 121 | the 3.3V output pin is off by default on boot. 122 | 123 | | State | Function | Default | 124 | |:-----:|:-----------------------------------------------------------------------:|:-------:| 125 | | High | Boot from SPI memory and run application | Yes | 126 | | Low | Boot to bootloader for USB-Serial-JTAG, USB-OTG or UART firmware upload | No | 127 | 128 | The ESP32-S3 has a capacitive touch controller. This peripheral allows you to 129 | use a conductive surface as a touch sensitive button. Not all pins can be used 130 | for touch sensing because of the complex analog circuitry involved. On Walter 131 | IO pins 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12 and 13 can be used for touch sensing. 132 | 133 | ## Internal pins 134 | 135 | There are some internal connections between the ESP32-S3 and the Sequans Monarch 136 | 2. These pins are not routed to Walter's header pins but if you want to port 137 | a new language to Walter you will need to know how the modem is connected. The 138 | following table gives an overview of the internal pin connections: 139 | 140 | | ESP32-S3 pin | Description | 141 | |:------------:|:-------------:| 142 | | IO19 | USB D- | 143 | | IO20 | USB D+ | 144 | | IO46 | LTE_WAKE0 | 145 | | IO48 | LTE UART0 TX | 146 | | IO14 | LTE UART0 RX | 147 | | IO21 | LTE UART0 RTS | 148 | | IO47 | LTE UART0 CTS | 149 | | IO45 | LTE RESET | 150 | 151 | ## Test pins 152 | 153 | ![drawing](img/walter-testpoints.svg) 154 | 155 | Walter contains 22 testpoints on the bottom of the board that serve multiple 156 | purposes. You can use these pins for debugging, interfacing and/or flashing of 157 | the Sequans GM02SP and the ESP32-S3-WROOM module. 158 | 159 | | Test pin number | Description | 160 | |:---------------:|:------------------------------:| 161 | | 1 | Sequans GM02SP JTAG TDO | 162 | | 2 | Sequans GM02SP JTAG TCK | 163 | | 3 | Sequans GM02SP JTAG TRSTN | 164 | | 4 | Sequans GM02SP JTAG TMS | 165 | | 5 | Sequans GM02SP JTAG TDI | 166 | | 6 | Sequans GM02SP PS status | 167 | | 7 | Sequans GM02SP RES/FFF FFH | 168 | | 8 | Sequans GM02SP RX0 | 169 | | 9 | Sequans GM02SP TX0 | 170 | | 10 | Sequans GM02SP TX1 | 171 | | 11 | Sequans GM02SP RX1 | 172 | | 12 | Sequans GM02SP RX2 | 173 | | 13 | Sequans GM02SP CTS0 | 174 | | 14 | Sequans GM02SP RTS0 | 175 | | 15 | Sequans GM02SP CTS1 | 176 | | 16 | Sequans GM02SP RTS1 | 177 | | 17 | Sequans GM02SP TX2 | 178 | | 18 | Walter input power | 179 | | 19 | 3.3V output (not switched) | 180 | | 20 | Sequans GM02SP 1.8V output | 181 | | 21 | Ground | 182 | | 22 | ESP32-S3 GPIO3 (strapping pin) | 183 | 184 | ## Sequans GM02SP UARTs 185 | 186 | The Sequans GM02SP module has 3 hardware UART interfaces. Only UART0 is 187 | connected to the ESP32-S3 Wroom Module on Walter as described in the 188 | [internal pins](#internal-pins) section. Communication between the ESP32-S3 189 | and the modem is possible with AT-commands. Please refer to the corresponding AT 190 | [command reference manual](https://quickspot.io/docs/file/gm02s_at_commands.pdf) 191 | of the Sequans GM02SP for all possible AT-commands. 192 | 193 | The UARTs have the following functionality by default: 194 | 195 | - UART0 (115200@8N1 with HW handshaking): used for AT commands. 196 | - UART1 (921600@8N1 with HW handshaking): used for manual firmware updates 197 | and/or custom software installation. 198 | - UART2 (115200@8N1 no HW handshaking): console log output. 199 | 200 | Please note that any UART host should be connected as follows: 201 | 202 | - RX <-> RX 203 | - TX <-> TX 204 | - RTS <-> RTS 205 | - CTS <-> CTS 206 | 207 | ## Electrical characteristics 208 | 209 | | Parameter | Units | Minimum rating | Typical rating | Maximum rating | 210 | |:------------------------:|:-----:|:--------------:|----------------|----------------| 211 | | DC supply voltage | V | 3.0 | 5.0 | 5.5 | 212 | | Digital I/O voltage | V | 2.64 | 3.3 | 3.6 | 213 | | Power consumption @ 3.3V | A | - | - | 1.5 | 214 | | 3.3V output current | mA | - | - | 250 | 215 | | Deep sleep current | µA | - | 9.8 | - | 216 | -------------------------------------------------------------------------------- /hardware/walter_feels.md: -------------------------------------------------------------------------------- 1 | ## Board overview 2 | 3 | ![drawing](img/walter-feels-transparent-01.png) 4 | 5 | Walter Feels is a reference design of a carrier board for Walter that can also 6 | be used as the basis of an IoT gateway. This carrier board has the following 7 | functionality: 8 | 9 | - Wide input range (2.5 - 26 V) MPPT power input 10 | - Single- to multi-cell and multi-chemistry (LiFePo, Li-Ion, Lead) battery 11 | charger. The board operates on voltages as low as 2.5V 12 | - I²C battery and power management (Analog Devices LTC4015) 13 | - MicroSD card slot 14 | - Sensors: temperature, humidity, barometric pressure, and 6 DoF IMU, 15 | - Sensor connectors: Sensirion SCD30 absolute CO₂ sensor (not included) 16 | - Multiple interfaces, including RS232, RS485, SDI-12, and CAN bus 17 | - 3.3, 5, and 12 V output 18 | - Two GPIO pins directly from the Walter board 19 | - I2C connector for other external sensors 20 | - Compatible with Takachi PFF13-4-13W housing for indoor applications 21 | 22 | ## MPPT power input 23 | 24 | *MPPT* stands for Maximum Power Point Tracking, it is a technique used with 25 | variable power sources to maximize energy extraction as conditions vary. This 26 | input is ideally suited to connect a renewable energy source such as a solar 27 | panel or wind generator. The input accepts any voltage between 2.5V and 26V. 28 | 29 | > Solar panel voltages are specified under load. When there is almost no load 30 | > the output voltage can get much higher which could damage the Walter Feels 31 | > board. You must make sure that the *Voc* or *open-circuit voltage* rating of 32 | > the panel doesn't exceed 26V 33 | 34 | ## Battery configuration 35 | 36 | Walter Feels' power management IC is the 37 | [Analog Devices LTC4015](https://www.analog.com/en/products/ltc4015.html) which 38 | supports the following battery chemistry and cell combinations: 39 | 40 | - Li-Ion/Polymer: up to 9 cells 41 | - LiFePO4: up to 9 cells 42 | - Lead-Acid (Liquid, Gel, AGM): 3, 6 or 12 cells 43 | 44 | The LTC4015 must be configured for the correct battery chemistry and cell count 45 | before the charger will engage. To do this you need to close the correct solder 46 | jumpers. The following table shows the configuration required to configure the 47 | cell count of the connected battery: 48 | 49 | | Cell count | CELLS0 | CELLS1 | CELLS2 | 50 | |:----------:|:------:|:------:|--------| 51 | | 1 | H | L | L | 52 | | 2 | L | H | L | 53 | | 3 | H | H | L | 54 | | 4 | Z | L | L | 55 | | 5 | L | Z | L | 56 | | 6 | Z | H | L | 57 | | 7 | H | Z | L | 58 | | 8 | Z | Z | L | 59 | | 9 | L | L | H | 60 | | 12 | H | H | H | 61 | 62 | Legend: 63 | 64 | - H: close the ON jumper, leave OFF jumper open. 65 | - L: close the OFF jumper, leave ON jumper open. 66 | - Z: leave ON and OFF jumper open. 67 | 68 | The below table gives an overview of the possible chemistries and how to 69 | configure them. If you choose the *programmable* option you must make sure to 70 | adopt your firmware to correctly configure charging parameters in the LTC4015. 71 | 72 | | Chemistry | CHEM0 | CHEM1 | 73 | |:-----------------------------:|:-----:|:-----:| 74 | | Li-Ion programmable | L | L | 75 | | Li-Ion 4.2V/cell fixed | H | H | 76 | | Li-Ion 4.1V/cell fixed | Z | L | 77 | | Li-Ion 4.0V/cell fixed | L | Z | 78 | | LiFePO4 programmable | H | L | 79 | | LiFePO4 fixed fast charge | Z | H | 80 | | LiFePO4 fixed standard charge | H | Z | 81 | | Lead-Acid fixed | Z | Z | 82 | | Lead-Acid programmable | L | H | 83 | 84 | Legend: 85 | 86 | - H: close the ON jumper, leave OFF jumper open. 87 | - L: close the OFF jumper, leave ON jumper open. 88 | - Z: leave ON and OFF jumper open. 89 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/arduino_esp-idf.md: -------------------------------------------------------------------------------- 1 | ## _Walter Modem Library /_ Arduino & ESP-IDF 2 | 3 | - [Setup](/walter-modem/arduino_esp-idf/setup/setup.md) 4 | - [Arduino](/walter-modem/arduino_esp-idf/setup/arduino.md) 5 | - [ESP-IDF](/walter-modem/arduino_esp-idf/setup/esp-idf.md) 6 | - [API Reference](/walter-modem/arduino_esp-idf/reference/reference.md) 7 | - [Sockets](/walter-modem/arduino_esp-idf/reference/sockets.md) 8 | - [HTTP](/walter-modem/arduino_esp-idf/reference/http.md) 9 | - [MQTT](/walter-modem/arduino_esp-idf/reference/mqtt.md) 10 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/reference/http.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [httpConfigProfile](#httpconfigprofile) 4 | - [httpSend](#httpsend) 5 | - [httpQuery](#httpquery) 6 | - [httpDidRing](#httpdidring) 7 | 8 | ## Enums Overview 9 | 10 | - [WalterModemHttpSendCmd](#waltermodemhttpsendcmd) 11 | - [WalterModemHttpQueryCmd](#waltermodemhttpquerycmd) 12 | - [WalterModemHttpPostParam](#waltermodemhttppostparam) 13 | 14 | --- 15 | 16 | ## Methods 17 | 18 | ### `httpConfigProfile` 19 | 20 | Configure a HTTP profile. 21 | 22 | This function will configure a HTTP profile 23 | with parameters such as server name and auth info. 24 | The profile info is stored persistently in the modem, so it is possible 25 | to store connection info once, using an Arduino sketch to prepare all settings, 26 | and later rely on this preconfigured profile in the modem without the need to 27 | set the parameters again in the actual Arduino sketch used in production. 28 | 29 | > [!WARNING] 30 | > You first need call tlsConfigProfile. 31 | 32 | > [!NOTE] 33 | > **File uploads/downloads** not supported. 34 | 35 | #### Example 36 | 37 | 38 | 39 | ##### **Arduino** 40 | 41 | ```cpp 42 | /** 43 | * @brief HTTP profile 44 | */ 45 | #define HTTP_PROFILE 1 46 | 47 | /** 48 | * @brief TLS profile 49 | */ 50 | #define TLS_PROFILE 1 51 | 52 | if(modem.httpConfigProfile(HTTP_PROFILE, "tls13.akamai.io", 443, TLS_PROFILE)) { 53 | Serial.println("http: Successfully configured the http profile"); 54 | } else { 55 | Serial.print("http: Failed to configure HTTP profile\r\n"); 56 | } 57 | ``` 58 | 59 | ##### **ESP-IDF** 60 | 61 | ```cpp 62 | /** 63 | * @brief HTTP profile 64 | */ 65 | #define HTTP_PROFILE 1 66 | 67 | /** 68 | * @brief TLS profile 69 | */ 70 | #define TLS_PROFILE 1 71 | 72 | if(modem.httpConfigProfile(HTTP_PROFILE, "tls13.akamai.io", 443, TLS_PROFILE)) { 73 | ESP_LOGI("http", "Successfully configured the HTTP profile"); 74 | } else { 75 | ESP_LOGE("http", "Failed to configure HTTP profile"); 76 | } 77 | ``` 78 | 79 | 80 | 81 | #### Params 82 | 83 | 84 | 85 | ##### **Arduino** 86 | 87 | | Param | Description | Default | 88 | | -------------- | --------------------------------------------------------------------------------------------------------------------- | --------- | 89 | | `profileId` | HTTP profile id (0, 1 or 2). | | 90 | | `serverName` | The server name to connect to. | | 91 | | `port` | The port of the server to connect to. | **80** | 92 | | `tlsProfileId` | If not 0, TLS is used with the given profile (1-6). | **0** | 93 | | `useBasicAuth` | Set true to use basic auth and send username/pw. | **false** | 94 | | `authUser` | Username. | **""** | 95 | | `authPass` | Password. | **""** | 96 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL is given the result is ignored. | **NULL** | 97 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 98 | | `args` | Optional argument to pass to the callback. | **NULL** | 99 | 100 | ##### **ESP-IDF** 101 | 102 | | Param | Description | Default | 103 | | -------------- | --------------------------------------------------------------------------------------------------------------------- | --------- | 104 | | `profileId` | HTTP profile id (0, 1 or 2). | | 105 | | `serverName` | The server name to connect to. | | 106 | | `port` | The port of the server to connect to. | **80** | 107 | | `tlsProfileId` | If not 0, TLS is used with the given profile (1-6). | **0** | 108 | | `useBasicAuth` | Set true to use basic auth and send username/pw. | **false** | 109 | | `authUser` | Username. | **""** | 110 | | `authPass` | Password. | **""** | 111 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL is given the result is ignored. | **NULL** | 112 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 113 | | `args` | Optional argument to pass to the callback. | **NULL** | 114 | 115 | 116 | 117 | #### Returns 118 | 119 | `bool` 120 | True on success, False otherwise. 121 | 122 | --- 123 | 124 | ### `httpSend` 125 | 126 | Perform a http **POST** or **PUT** request. 127 | 128 | No need to first open the connection with the buggy httpConnect command 129 | unless you need TLS + a private key. 130 | 131 | #### Example 132 | 133 | 134 | 135 | ##### **Arduino** 136 | 137 | ```cpp 138 | /** 139 | * @brief The buffer to transmit to the HTTP server. 140 | */ 141 | uint8_t dataBuf[8] = { 0 }; 142 | 143 | /** 144 | * @brief Buffer for incoming HTTP response 145 | */ 146 | uint8_t incomingBuf[256] = { 0 }; 147 | 148 | if(modem.httpSend(HTTP_PROFILE, "/", dataBuf, 8, WALTER_MODEM_HTTP_SEND_CMD_POST, WALTER_MODEM_HTTP_POST_PARAM_OCTET_STREAM, ctbuf, sizeof(ctbuf))) { 149 | Serial.println("http: query performed"); 150 | } else { 151 | Serial.println("http: query failed"); 152 | } 153 | ``` 154 | 155 | ##### **ESP-IDF** 156 | 157 | ```cpp 158 | /** 159 | * @brief The buffer to transmit to the HTTP server. 160 | */ 161 | uint8_t dataBuf[8] = { 0 }; 162 | 163 | /** 164 | * @brief Buffer for incoming HTTP response 165 | */ 166 | uint8_t incomingBuf[256] = { 0 }; 167 | 168 | if(modem.httpSend(HTTP_PROFILE, "/", dataBuf, 8, WALTER_MODEM_HTTP_SEND_CMD_POST, WALTER_MODEM_HTTP_POST_PARAM_OCTET_STREAM, ctbuf, sizeof(ctbuf))) { 169 | ESP_LOGI("http", "query performed"); 170 | } else { 171 | ESP_LOGE("http", "query failed"); 172 | } 173 | ``` 174 | 175 | 176 | 177 | #### Params 178 | 179 | 180 | 181 | ##### **Arduino** 182 | 183 | | Param | Description | Default | 184 | | -------------------- | --------------------------------------------------------- | -------------------------------------------- | 185 | | `profileId` | The profile id (0, 1 or 2) of the HTTP context. | | 186 | | `uri` | The URI. | | 187 | | `data` | Data to be sent to the server. | | 188 | | `dataSize` | Length of the data buffer to be sent to the server. | | 189 | | `httpSendCmd` | POST or PUT [command](#waltermodemhttpsendcmd). | **WALTER_MODEM_HTTP_SEND_CMD_POST** | 190 | | `httpPostParam` | [Content type](#waltermodemhttppostparam) *(enum value)*. | **WALTER_MODEM_HTTP_POST_PARAM_UNSPECIFIED** | 191 | | `contentTypeBuf` | Optional user buffer to store content type header in. | **NULL** | 192 | | `contentTypeBufSize` | Size of the user buffer, including terminating null byte. | **0** | 193 | | `rsp` | Response object. | **NULL** | 194 | | `cb` | Callback. | **NULL** | 195 | | `args` | Callback arguments. | **NULL** | 196 | 197 | ##### **ESP-IDF** 198 | 199 | | Param | Description | Default | 200 | | -------------------- | --------------------------------------------------------- | -------------------------------------------- | 201 | | `profileId` | The profile id (0, 1 or 2) of the HTTP context. | | 202 | | `uri` | The URI. | | 203 | | `data` | Data to be sent to the server. | | 204 | | `dataSize` | Length of the data buffer to be sent to the server. | | 205 | | `httpSendCmd` | POST or PUT [command](#waltermodemhttpsendcmd). | **WALTER_MODEM_HTTP_SEND_CMD_POST** | 206 | | `httpPostParam` | [Content type](#waltermodemhttppostparam) *(enum value)*. | **WALTER_MODEM_HTTP_POST_PARAM_UNSPECIFIED** | 207 | | `contentTypeBuf` | Optional user buffer to store content type header in. | **NULL** | 208 | | `contentTypeBufSize` | Size of the user buffer, including terminating null byte. | **0** | 209 | | `rsp` | Response object. | **NULL** | 210 | | `cb` | Callback. | **NULL** | 211 | | `args` | Callback arguments. | **NULL** | 212 | 213 | ##### **Micropython** 214 | 215 | 216 | 217 | #### Returns 218 | 219 | `bool` 220 | True on success, False otherwise. 221 | 222 | --- 223 | 224 | ### `httpQuery` 225 | 226 | Perform a http **GET**, **DELETE** or **HEAD** request. 227 | 228 | No need to first open the connection with the buggy httpConnect command 229 | unless you need TLS + a private key. 230 | 231 | #### Example 232 | 233 | 234 | 235 | ##### **Arduino** 236 | 237 | ```cpp 238 | static char ctbuf[32]; 239 | 240 | if(modem.httpQuery(HTTP_PROFILE, "/", WALTER_MODEM_HTTP_QUERY_CMD_GET, ctbuf, sizeof(ctbuf))) { 241 | Serial.println("http: query performed"); 242 | } else { 243 | Serial.println("http query failed"); 244 | ESP.restart(); 245 | } 246 | ``` 247 | 248 | ##### **ESP-IDF** 249 | 250 | ```cpp 251 | static char ctbuf[32]; 252 | 253 | if(modem.httpQuery(HTTP_PROFILE, "/", WALTER_MODEM_HTTP_QUERY_CMD_GET, ctbuf, sizeof(ctbuf))) { 254 | ESP_LOGI("http", "query performed"); 255 | } else { 256 | ESP_LOGI("http", "query failed"); 257 | esp_restart(); 258 | } 259 | ``` 260 | 261 | 262 | 263 | #### Params 264 | 265 | 266 | 267 | ##### **Arduino** 268 | 269 | | Param | Description | Default | 270 | | -------------------- | --------------------------------------------------------- | ----------------------------------- | 271 | | `profileId` | The profile id *(0, 1, or 2)* of the HTTP context. | | 272 | | `uri` | The URI. | | 273 | | `httpQueryCmd` | GET, DELETE, or HEAD [command](#waltermodemhttpquerycmd). | **WALTER_MODEM_HTTP_QUERY_CMD_GET** | 274 | | `contentTypeBuf` | Optional user buffer to store content type header in. | **NULL** | 275 | | `contentTypeBufSize` | Size of the user buffer, including terminating null byte. | **0** | 276 | | `rsp` | Response object. | **NULL** | 277 | | `cb` | Callback. | **NULL** | 278 | | `args` | Callback arguments. | **NULL** | 279 | 280 | ##### **ESP-IDF** 281 | 282 | | Param | Description | Default | 283 | | -------------------- | --------------------------------------------------------- | ----------------------------------- | 284 | | `profileId` | The profile id *(0, 1, or 2)* of the HTTP context. | | 285 | | `uri` | The URI. | | 286 | | `httpQueryCmd` | GET, DELETE, or HEAD [command](#waltermodemhttpquerycmd). | **WALTER_MODEM_HTTP_QUERY_CMD_GET** | 287 | | `contentTypeBuf` | Optional user buffer to store content type header in. | **NULL** | 288 | | `contentTypeBufSize` | Size of the user buffer, including terminating null byte. | **0** | 289 | | `rsp` | Response object. | **NULL** | 290 | | `cb` | Callback. | **NULL** | 291 | | `args` | Callback arguments. | **NULL** | 292 | 293 | 294 | 295 | #### Returns 296 | 297 | `bool` 298 | True on success, False otherwise. 299 | 300 | --- 301 | 302 | ### `httpDidRing` 303 | 304 | Fetch http response to earlier http request, if any 305 | 306 | #### Example 307 | 308 | 309 | 310 | ##### **Arduino** 311 | 312 | ```cpp 313 | /** 314 | * @brief Buffer for incoming HTTP response 315 | */ 316 | uint8_t incomingBuf[256] = { 0 }; 317 | 318 | /** 319 | * @brief How many times we have left to receive response 320 | */ 321 | static short httpReceiveAttemptsLeft = 0; 322 | 323 | /** 324 | * @brief Buffer for Content-Type 325 | */ 326 | static char ctbuf[32]; 327 | 328 | 329 | /* while loop so we can fetch old responses as well as the expected response */ 330 | while(modem.httpDidRing(HTTP_PROFILE, incomingBuf, sizeof(incomingBuf), &rsp)) { 331 | httpReceiveAttemptsLeft = 0; 332 | 333 | Serial.printf("http: status code: %d\r\n", rsp.data.httpResponse.httpStatus); 334 | Serial.printf("http: content type: %s\r\n", ctbuf); 335 | Serial.printf("http: [%s]\r\n", incomingBuf); 336 | } 337 | ``` 338 | 339 | ##### **ESP-IDF** 340 | 341 | ```cpp 342 | /** 343 | * @brief Buffer for incoming HTTP response 344 | */ 345 | uint8_t incomingBuf[256] = { 0 }; 346 | 347 | /** 348 | * @brief How many times we have left to receive response 349 | */ 350 | static short httpReceiveAttemptsLeft = 0; 351 | 352 | /** 353 | * @brief Buffer for Content-Type 354 | */ 355 | static char ctbuf[32]; 356 | 357 | 358 | /* while loop so we can fetch old responses as well as the expected response */ 359 | while(modem.httpDidRing(HTTP_PROFILE, incomingBuf, sizeof(incomingBuf), &rsp)) { 360 | httpReceiveAttemptsLeft = 0; 361 | 362 | ESP_LOGI("http", "status code: %d", rsp.data.httpResponse.httpStatus); 363 | ESP_LOGI("http", "content type: %s", ctbuf); 364 | ESP_LOGI("http", "[%s]\r\n", incomingBuf); 365 | } 366 | ``` 367 | 368 | 369 | 370 | #### Params 371 | 372 | 373 | 374 | ##### **Arduino** 375 | 376 | | Param | Description | Default | 377 | | --------------- | --------------------------------------------------------------------------- | -------- | 378 | | `profileId` | Profile for which to get the response. | | 379 | | `targetBuf` | User buffer to store response in. | | 380 | | `targetBufSize` | Size of the user buffer, including space for a terminating null byte. | | 381 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 382 | 383 | ##### **ESP-IDF** 384 | 385 | | Param | Description | Default | 386 | | --------------- | --------------------------------------------------------------------------- | -------- | 387 | | `profileId` | Profile for which to get the response. | | 388 | | `targetBuf` | User buffer to store response in. | | 389 | | `targetBufSize` | Size of the user buffer, including space for a terminating null byte. | | 390 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 391 | 392 | 393 | 394 | #### Returns 395 | 396 | `bool` 397 | True on success, False otherwise. 398 | 399 | --- 400 | 401 | ## Enums 402 | 403 | ### `WalterModemHttpSendCmd` 404 | 405 | The possible commands for a HTTP send operation. 406 | 407 | 408 | 409 | #### **Arduino** 410 | 411 | > **WALTER_MODEM_HTTP_SEND_CMD_POST** = `0` \ 412 | > Perform a POST request \ 413 | > **WALTER_MODEM_HTTP_SEND_CMD_PUT** = `1` \ 414 | > Perform PUT request 415 | 416 | #### **ESP-IDF** 417 | 418 | > **WALTER_MODEM_HTTP_SEND_CMD_POST** = `0` \ 419 | > Perform a POST request \ 420 | > **WALTER_MODEM_HTTP_SEND_CMD_PUT** = `1` \ 421 | > Perform PUT request 422 | 423 | 424 | 425 | ### `WalterModemHttpQueryCmd` 426 | 427 | The possible commands for a HTTP query operation. 428 | 429 | 430 | 431 | #### **Arduino** 432 | 433 | > **WALTER_MODEM_HTTP_QUERY_CMD_GET** = `0` \ 434 | > Perform a GET request \ 435 | > **WALTER_MODEM_HTTP_QUERY_CMD_HEAD** = `1` \ 436 | > Perform a HEAD request \ 437 | > **WALTER_MODEM_HTTP_QUERY_CMD_DELETE** = `2` \ 438 | > Perform a DELETE request 439 | 440 | #### **ESP-IDF** 441 | 442 | > **WALTER_MODEM_HTTP_QUERY_CMD_GET** = `0` \ 443 | > Perform a GET request \ 444 | > **WALTER_MODEM_HTTP_QUERY_CMD_HEAD** = `1` \ 445 | > Perform a HEAD request \ 446 | > **WALTER_MODEM_HTTP_QUERY_CMD_DELETE** = `2` \ 447 | > Perform a DELETE request 448 | 449 | 450 | 451 | ### `WalterModemHttpPostParam` 452 | 453 | The possible post params for a HTTP send operation. 454 | 455 | 456 | 457 | #### **Arduino** 458 | 459 | > **WALTER_MODEM_HTTP_POST_PARAM_URL_ENCODED** = `0` \ 460 | > Param type is encoded in the url \ 461 | > **WALTER_MODEM_HTTP_POST_PARAM_TEXT_PLAIN** = `1` \ 462 | > Param is plain text \ 463 | > **WALTER_MODEM_HTTP_POST_PARAM_OCTET_STREAM** = `2` \ 464 | > Param is an octet/byte stream \ 465 | > **WALTER_MODEM_HTTP_POST_PARAM_FORM_DATA** = `3` \ 466 | > Param is form data \ 467 | > **WALTER_MODEM_HTTP_POST_PARAM_JSON** = `4` \ 468 | > Param is JSON \ 469 | > **WALTER_MODEM_HTTP_POST_PARAM_UNSPECIFIED** = `99` \ 470 | > Param is unspecified 471 | 472 | #### **ESP-IDF** 473 | 474 | > **WALTER_MODEM_HTTP_POST_PARAM_URL_ENCODED** = `0` \ 475 | > Param type is encoded in the url \ 476 | > **WALTER_MODEM_HTTP_POST_PARAM_TEXT_PLAIN** = `1` \ 477 | > Param is plain text \ 478 | > **WALTER_MODEM_HTTP_POST_PARAM_OCTET_STREAM** = `2` \ 479 | > Param is an octet/byte stream \ 480 | > **WALTER_MODEM_HTTP_POST_PARAM_FORM_DATA** = `3` \ 481 | > Param is form data \ 482 | > **WALTER_MODEM_HTTP_POST_PARAM_JSON** = `4` \ 483 | > Param is JSON \ 484 | > **WALTER_MODEM_HTTP_POST_PARAM_UNSPECIFIED** = `99` \ 485 | > Param is unspecified 486 | 487 | 488 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/reference/mqtt.md: -------------------------------------------------------------------------------- 1 | # MQTT 2 | 3 | ## Methods Overview 4 | 5 | - [mqttConnect](#mqttconnect) 6 | - [mqttSubscribe](#mqttsubscribe) 7 | - [mqttPublish](#mqttpublish) 8 | - [mqttDidRing](#mqttdidring) 9 | 10 | --- 11 | 12 | ## Methods 13 | 14 | ### `mqttConnect` 15 | 16 | Initialize MQTT and establish a connection. 17 | 18 | #### Example 19 | 20 | 21 | 22 | ##### **Arduino** 23 | 24 | ```cpp 25 | if(modem.mqttConnect("test.mosquitto.org", 8883, macString, "user", "pass", 1)) { 26 | Serial.println("mqtt: connection succeeded"); 27 | } else { 28 | Serial.println("mqtt: connection failed"); 29 | } 30 | ``` 31 | 32 | ##### **ESP-IDF** 33 | 34 | ```cpp 35 | if(modem.mqttConnect("test.mosquitto.org", 8883, macString, "user", "pass", 1)) { 36 | ESP_LOGI("mqtt", "connection succeeded"); 37 | } else { 38 | ESP_LOGI("mqtt", "connection failed"); 39 | } 40 | ``` 41 | 42 | 43 | 44 | #### Params 45 | 46 | 47 | 48 | ##### **Arduino** 49 | 50 | | Param | Description | Default | 51 | | -------------- | ------------------------------------------------------------------------------------------------------ | ------------------------ | 52 | | `serverName` | MQTT broker hostname. | | 53 | | `port` | Port to connect to. | | 54 | | `clientId` | Client ID string to be used. | **"walter-mqtt-client"** | 55 | | `userName` | Username. | **""** | 56 | | `password` | Password. | **""** | 57 | | `tlsProfileId` | TLS profile ID to be used *(default 0 = plaintext)*. | **0** | 58 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 59 | | `cb` | Optional callback argument. When not NULL, this function returns immediately. | **NULL** | 60 | | `args` | Optional argument to pass to the callback. | **NULL** | 61 | 62 | ##### **ESP-IDF** 63 | 64 | | Param | Description | Default | 65 | | -------------- | ------------------------------------------------------------------------------------------------------ | ------------------------ | 66 | | `serverName` | MQTT broker hostname. | | 67 | | `port` | Port to connect to. | | 68 | | `clientId` | Client ID string to be used. | **"walter-mqtt-client"** | 69 | | `userName` | Username. | **""** | 70 | | `password` | Password. | **""** | 71 | | `tlsProfileId` | TLS profile ID to be used *(default 0 = plaintext)*. | **0** | 72 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 73 | | `cb` | Optional callback argument. When not NULL, this function returns immediately. | **NULL** | 74 | | `args` | Optional argument to pass to the callback. | **NULL** | 75 | 76 | 77 | 78 | #### Returns 79 | 80 | `bool` 81 | True on success, False otherwise. 82 | 83 | --- 84 | 85 | ### `mqttSubscribe` 86 | 87 | Subscribe to a MQTT topic 88 | 89 | This function subscribes to a given topic using the connection established 90 | earlier through [mqttConnect](#mqttconnect). 91 | 92 | #### Example 93 | 94 | 95 | 96 | ##### **Arduino** 97 | 98 | ```cpp 99 | if(modem.mqttSubscribe("waltertopic")) { 100 | Serial.println("mqtt: subscribed to topic waltertopic"); 101 | } else { 102 | Serial.println("mqtt: subscribe failed"); 103 | } 104 | ``` 105 | 106 | ##### **ESP-IDF** 107 | 108 | ```cpp 109 | if(modem.mqttSubscribe("waltertopic")) { 110 | ESP_LOGI("mqtt", "subscribed to topic waltertopic"); 111 | } else { 112 | ESP_LOGI("mqtt", "subscribe failed"); 113 | } 114 | ``` 115 | 116 | 117 | 118 | #### Params 119 | 120 | 121 | 122 | ##### **Arduino** 123 | 124 | | Param | Description | Default | 125 | | ------------- | ------------------------------------------------------------------------------------------------------ | -------- | 126 | | `topicString` | Topic to publish on. | | 127 | | `qos` | QoS: 0 = at most once, 1 = at least once, 2 = exactly once received. | **1** | 128 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 129 | | `cb` | Optional callback argument. When not NULL, this function returns immediately. | **NULL** | 130 | | `args` | Optional argument to pass to the callback. | **NULL** | 131 | 132 | ##### **ESP-IDF** 133 | 134 | | Param | Description | Default | 135 | | ------------- | ------------------------------------------------------------------------------------------------------ | -------- | 136 | | `topicString` | Topic to publish on. | | 137 | | `qos` | QoS: 0 = at most once, 1 = at least once, 2 = exactly once received. | **1** | 138 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 139 | | `cb` | Optional callback argument. When not NULL, this function returns immediately. | **NULL** | 140 | | `args` | Optional argument to pass to the callback. | **NULL** | 141 | 142 | 143 | 144 | #### Returns 145 | 146 | `bool` 147 | True on success, False otherwise. 148 | 149 | --- 150 | 151 | ### `mqttPublish` 152 | 153 | Publish something through mqtt. 154 | 155 | This function publishes the passed data on the given mqtt topic using the 156 | connection established earlier through [mqttConnect](#mqttconnect). 157 | 158 | #### Example 159 | 160 | 161 | 162 | ##### **Arduino** 163 | 164 | ```cpp 165 | static char outgoingMsg[64]; 166 | 167 | if(modem.mqttPublish("waltertopic", (uint8_t *) outgoingMsg, strlen(outgoingMsg))) { 168 | Serial.printf("mqtt: published: %s, on topic waltertopic \r\n", outgoingMsg); 169 | } else { 170 | Serial.println("mqtt: publish failed"); 171 | } 172 | ``` 173 | 174 | ##### **ESP-IDF** 175 | 176 | ```cpp 177 | static char outgoingMsg[64]; 178 | 179 | if(modem.mqttPublish("waltertopic", (uint8_t *) outgoingMsg, strlen(outgoingMsg))) { 180 | ESP_LOGI("mqtt_test", "published: %s on topic waltertopic", outgoingMsg); 181 | } else { 182 | ESP_LOGI("mqtt_test", "MQTT publish failed"); 183 | } 184 | ``` 185 | 186 | 187 | 188 | #### Params 189 | 190 | 191 | 192 | ##### **Arduino** 193 | 194 | | Param | Description | Default | 195 | | ------------- | ------------------------------------------------------------------------------------------------------ | -------- | 196 | | `topicString` | Topic to publish on. | | 197 | | `data` | Data to be published. | | 198 | | `dataSize` | Size of the data block. | | 199 | | `qos` | QoS: 0 = at most once, 1 = at least once, 2 = exactly once received. | **1** | 200 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 201 | | `cb` | Optional callback argument. When not NULL, this function returns immediately. | **NULL** | 202 | | `args` | Optional argument to pass to the callback. | **NULL** | 203 | 204 | ##### **ESP-IDF** 205 | 206 | | Param | Description | Default | 207 | | ------------- | ------------------------------------------------------------------------------------------------------ | -------- | 208 | | `topicString` | Topic to publish on. | | 209 | | `data` | Data to be published. | | 210 | | `dataSize` | Size of the data block. | | 211 | | `qos` | QoS: 0 = at most once, 1 = at least once, 2 = exactly once received. | **1** | 212 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 213 | | `cb` | Optional callback argument. When not NULL, this function returns immediately. | **NULL** | 214 | | `args` | Optional argument to pass to the callback. | **NULL** | 215 | 216 | 217 | 218 | #### Returns 219 | 220 | `bool` 221 | True on success, False otherwise. 222 | 223 | --- 224 | 225 | ### `mqttDidRing` 226 | 227 | Poll if there were incoming MQTT messages 228 | 229 | Poll if the modem has reported any incoming MQTT messages 230 | on the topics we are subscribed on. 231 | 232 | > [!NOTE] 233 | > No more than 1 message with QoS 0 is stored in the buffer, 234 | > every new message with QoS 0 overwrites the previous. 235 | 236 | #### Example 237 | 238 | 239 | 240 | ##### **Arduino** 241 | 242 | ```cpp 243 | while (modem.mqttDidRing("waltertopic", incomingBuf, sizeof(incomingBuf), &rsp)) { 244 | Serial.printf("mqtt: incoming: qos=%d msgid=%d len=%d:\r\n", 245 | rsp.data.mqttResponse.qos, 246 | rsp.data.mqttResponse.messageId, 247 | rsp.data.mqttResponse.length); 248 | for (int i = 0; i < rsp.data.mqttResponse.length; i++) { 249 | Serial.printf("mqtt: %c, 0x%02x\r\n", incomingBuf[i], incomingBuf[i]); 250 | } 251 | } 252 | ``` 253 | 254 | ##### **ESP-IDF** 255 | 256 | ```cpp 257 | while(modem.mqttDidRing("waltertopic", incomingBuf, sizeof(incomingBuf), &rsp)) { 258 | ESP_LOGI("mqtt", "incoming: qos=%d msgid=%d len=%d:", 259 | rsp.data.mqttResponse.qos, 260 | rsp.data.mqttResponse.messageId, 261 | rsp.data.mqttResponse.length); 262 | for(int i = 0; i < rsp.data.mqttResponse.length; i++) { 263 | ESP_LOGI("mqtt:", "%c, 0x%02x", incomingBuf[i], incomingBuf[i]); 264 | } 265 | } 266 | ``` 267 | 268 | 269 | 270 | #### Params 271 | 272 | 273 | 274 | ##### **Arduino** 275 | 276 | | Param | Description | Default | 277 | | --------------- | ------------------------------------------------------------------------------------------------------ | -------- | 278 | | `topic` | Topic to poll. | | 279 | | `targetBuf` | Target buffer to write incoming MQTT data in; | | 280 | | `targetBufSize` | Size of the target buffer. | | 281 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 282 | 283 | ##### **ESP-IDF** 284 | 285 | | Param | Description | Default | 286 | | --------------- | ------------------------------------------------------------------------------------------------------ | -------- | 287 | | `topic` | Topic to poll. | | 288 | | `targetBuf` | Target buffer to write incoming MQTT data in; | | 289 | | `targetBufSize` | Size of the target buffer. | | 290 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL, result ignored. | **NULL** | 291 | 292 | 293 | 294 | #### Returns 295 | 296 | `bool` 297 | True on success, False 298 | if no message(s) arrived, error or if no message(s) are expected *(eg no ring received)*. 299 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/reference/reference.md: -------------------------------------------------------------------------------- 1 | ## _Walter Modem Library / Arduino & ESP-IDF /_ API Reference 2 | 3 | - [Sockets](/walter-modem/arduino_esp-idf/reference/sockets.md) 4 | - [HTTP](/walter-modem/arduino_esp-idf/reference/http.md) 5 | - [MQTT](/walter-modem/arduino_esp-idf/reference/mqtt.md) 6 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/reference/sockets.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [createSocket](#createsocket) 4 | - [configSocket](#configsocket) 5 | - [connectSocket](#connectsocket) 6 | - [socketSend](#socketsend) 7 | - [closeSocket](#closesocket) 8 | 9 | ## Enums Overview 10 | 11 | - [WalterModemSocketProto](#waltermodemsocketproto) 12 | - [WalterModemSocketAcceptAnyRemote](#waltermodemsocketacceptanyremote) 13 | 14 | --- 15 | 16 | ## Methods 17 | 18 | ### `createSocket` 19 | 20 | Create a new socket in a certain PDP context. 21 | 22 | This function will create a new socket. 23 | After socket creation one can set additional socket settings 24 | and use the socket for communication. 25 | 26 | > [!NOTE] 27 | > id's are from **1-6**. 28 | 29 | #### Example 30 | 31 | 32 | 33 | ##### **Arduino** 34 | 35 | ```cpp 36 | WalterModemRsp rsp = {}; 37 | int socketId = 0; 38 | if(modem.createSocket(&rsp)) { 39 | Serial.printf("socket created successfully\n"); 40 | socketId = rsp.data.socketId; 41 | } 42 | ``` 43 | 44 | ##### **ESP-IDF** 45 | 46 | ```cpp 47 | WalterModemRsp rsp = {}; 48 | int socketId = 0; 49 | if(modem.createSocket(&rsp)) { 50 | ESP_LOGI("socket", "created successfully"); 51 | socketId = rsp.data.socketId; 52 | } 53 | ``` 54 | 55 | 56 | 57 | #### Params 58 | 59 | 60 | 61 | ##### **Arduino** 62 | 63 | | Param | Description | Default | 64 | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | ----------- | 65 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL is given the result is ignored. | | 66 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **nullptr** | 67 | | `args` | Optional argument to pass to the callback. | **nullptr** | 68 | | `pdpCtxId` | The PDP context id or -1 to re-use the last one. | **-1** | 69 | | `mtu` | The maximum transmission unit used by the socket. | **300** | 70 | | `exchangeTimeout` | The maximum number of seconds this socket can be inactive. | **90** | 71 | | `connTimeout` | The maximum number of seconds this socket is allowed to try to connect. | **60** | 72 | | `sendDelayMs` | The number of milliseconds send delay. | **5000** | 73 | 74 | ##### **ESP-IDF** 75 | 76 | | Param | Description | Default | 77 | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | ----------- | 78 | | `rsp` | Pointer to a modem response structure to save the result of the command in. When NULL is given the result is ignored. | | 79 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **nullptr** | 80 | | `args` | Optional argument to pass to the callback. | **nullptr** | 81 | | `pdpCtxId` | The PDP context id or -1 to re-use the last one. | **-1** | 82 | | `mtu` | The maximum transmission unit used by the socket. | **300** | 83 | | `exchangeTimeout` | The maximum number of seconds this socket can be inactive. | **90** | 84 | | `connTimeout` | The maximum number of seconds this socket is allowed to try to connect. | **60** | 85 | | `sendDelayMs` | The number of milliseconds send delay. | **5000** | 86 | 87 | 88 | 89 | #### Returns 90 | 91 | `bool` 92 | True on success, False otherwise. 93 | 94 | --- 95 | 96 | ### `configSocket` 97 | 98 | This step is required for the library 99 | to correctly configure the modem to use this socket. 100 | 101 | #### Example 102 | 103 | 104 | 105 | ##### **Arduino** 106 | 107 | ```cpp 108 | if(modem.configSocket()) { 109 | Serial.printf("socket: Successfully configured the socket\n"); 110 | } else { 111 | Serial.printf("socket: Could not configure the socket\n"); 112 | } 113 | ``` 114 | 115 | ##### **ESP-IDF** 116 | 117 | ```cpp 118 | if(modem.configSocket()) { 119 | ESP_LOGI("socket", "Successfully configured the socket"); 120 | } else { 121 | ESP_LOGI("socket", "Could not configure the socket"); 122 | } 123 | ``` 124 | 125 | 126 | 127 | #### Params 128 | 129 | 130 | 131 | ##### **Arduino** 132 | 133 | | Param | Description | Default | 134 | | ---------- | -------------------------------------------------------------------------------- | -------- | 135 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 136 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 137 | | `args` | Optional argument to pass to the callback. | **NULL** | 138 | | `socketId` | The id of the socket to connect or **-1 to re-use the last one.** | **-1** | 139 | 140 | ##### **ESP-IDF** 141 | 142 | | Param | Description | Default | 143 | | ---------- | -------------------------------------------------------------------------------- | -------- | 144 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 145 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 146 | | `args` | Optional argument to pass to the callback. | **NULL** | 147 | | `socketId` | The id of the socket to connect or **-1 to re-use the last one.** | **-1** | 148 | 149 | 150 | 151 | #### Returns 152 | 153 | `bool` 154 | True on success, False otherwise. 155 | 156 | --- 157 | 158 | ### `connectSocket` 159 | 160 | Connect a socket after which data can be exchanged. 161 | 162 | This function will connect a socket to a remote host. 163 | When the connection was successful data can be exchanged. 164 | 165 | #### Example 166 | 167 | 168 | 169 | ##### **Arduino** 170 | 171 | ```cpp 172 | /** 173 | * @brief The address of the server to upload the data to. 174 | */ 175 | #define SERV_ADDR "64.225.64.140" 176 | 177 | /** 178 | * @brief The port on which the server is listening. 179 | */ 180 | #define SERV_PORT 1999 181 | 182 | if(modem.connectSocket(SERV_ADDR, SERV_PORT, SERV_PORT)) { 183 | Serial.printf("socket: Connected to server %s:%d\n", SERV_ADDR, SERV_PORT); 184 | } else { 185 | Serial.printf("socket: Could not connect socket\n"); 186 | } 187 | 188 | ``` 189 | 190 | ##### **ESP-IDF** 191 | 192 | ```cpp 193 | /** 194 | * @brief The address of the server to upload the data to. 195 | */ 196 | #define SERV_ADDR "64.225.64.140" 197 | 198 | /** 199 | * @brief The port on which the server is listening. 200 | */ 201 | #define SERV_PORT 1999 202 | 203 | if(modem.connectSocket(SERV_ADDR, SERV_PORT, SERV_PORT)) { 204 | ESP_LOGI("socket", "Connected to server %s:%d", SERV_ADDR, SERV_PORT); 205 | } else { 206 | ESP_LOGI("socket", "Could not connect socket"); 207 | } 208 | ``` 209 | 210 | 211 | 212 | #### Params 213 | 214 | 215 | 216 | ##### **Arduino** 217 | 218 | | Param | Description | Default | 219 | | ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------- | 220 | | `remoteHost` | The remote IPv4/IPv6 or hostname to connect to. | | 221 | | `remotePort` | The remote port to connect on. | | 222 | | `localPort` | The local port in case of a UDP socket. | **0** | 223 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 224 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 225 | | `args` | Optional argument to pass to the callback. | **NULL** | 226 | | `protocol` | The [protocol](#waltermodemsocketproto) to use, UDP by default. | **WALTER_MODEM_SOCKET_PROTO_UDP** | 227 | | `acceptAnyRemote` | How to [accept remote](#waltermodemsocketacceptanyremote) UDP packets. | **WALTER_MODEM_ACCEPT_ANY_REMOTE_DISABLED** | 228 | | `socketId` | The id of the socket to connect or **-1 to re-use the last one**. | **-1** | 229 | 230 | ##### **ESP-IDF** 231 | 232 | | Param | Description | Default | 233 | | ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------- | 234 | | `remoteHost` | The remote IPv4/IPv6 or hostname to connect to. | | 235 | | `remotePort` | The remote port to connect on. | | 236 | | `localPort` | The local port in case of a UDP socket. | **0** | 237 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 238 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 239 | | `args` | Optional argument to pass to the callback. | **NULL** | 240 | | `protocol` | The [protocol](#waltermodemsocketproto) to use, UDP by default. | **WALTER_MODEM_SOCKET_PROTO_UDP** | 241 | | `acceptAnyRemote` | How to [accept remote](#waltermodemsocketacceptanyremote) UDP packets. | **WALTER_MODEM_ACCEPT_ANY_REMOTE_DISABLED** | 242 | | `socketId` | The id of the socket to connect or **-1 to re-use the last one**. | **-1** | 243 | 244 | 245 | 246 | #### Returns 247 | 248 | `bool` 249 | True on success, False otherwise. 250 | 251 | --- 252 | 253 | ### `socketSend` 254 | 255 | Send data over a socket. 256 | 257 | This function will send data over a socket. 258 | 259 | > [!WARNING] 260 | > The data buffer **cannot be freed** until the send response is received 261 | > (sync or async). 262 | 263 | > [!NOTE] 264 | > The maximum size of the data buffer is **1500 bytes**. 265 | 266 | #### Example 267 | 268 | 269 | 270 | ##### **Arduino** 271 | 272 | ```cpp 273 | /** 274 | * @brief The buffer to transmit to the UDP server. The first 6 bytes will be 275 | * the MAC address of the Walter this code is running on. 276 | */ 277 | uint8_t dataBuf[8] = { 0 }; 278 | esp_read_mac(dataBuf, ESP_MAC_WIFI_STA); 279 | 280 | dataBuf[6] = counter >> 8; 281 | dataBuf[7] = counter & 0xFF; 282 | 283 | if(modem.socketSend(dataBuf, 8)) { 284 | Serial.printf("socket: Transmitted data %d\n", counter); 285 | counter += 1; 286 | } else { 287 | Serial.printf("socket: Could not transmit data\n"); 288 | delay(1000); 289 | ESP.restart(); 290 | } 291 | 292 | ``` 293 | 294 | ##### **ESP-IDF** 295 | 296 | ```cpp 297 | /** 298 | * @brief The buffer to transmit to the UDP server. The first 6 bytes will be 299 | * the MAC address of the Walter this code is running on. 300 | */ 301 | uint8_t dataBuf[8] = { 0 }; 302 | esp_read_mac(dataBuf, ESP_MAC_WIFI_STA); 303 | 304 | dataBuf[6] = counter >> 8; 305 | dataBuf[7] = counter & 0xFF; 306 | 307 | if(modem.socketSend(dataBuf, 8)) { 308 | ESP_LOGI("socket", "Transmitted data %d", counter); 309 | counter += 1; 310 | } else { 311 | ESP_LOGI("socket", "Could not transmit data"); 312 | vTaskDelay(pdMS_TO_TICKS(1000)); 313 | esp_restart(); 314 | } 315 | ``` 316 | 317 | 318 | 319 | #### params 320 | 321 | 322 | 323 | ##### **Arduino** 324 | 325 | | Param | Description | Default | 326 | | ---------- | -------------------------------------------------------------------------------- | ---------------------------- | 327 | | `data` | The data to send. | | 328 | | `dataSize` | The number of bytes to transmit. | | 329 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 330 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 331 | | `args` | Optional argument to pass to the callback. | **NULL** | 332 | | `rai` | The release assistance information. | **WALTER_MODEM_RAI_NO_INFO** | 333 | | `socketId` | The id of the socket to close or **-1 to re-use the last one.** | **-1** | 334 | 335 | ##### **ESP-IDF** 336 | 337 | | Param | Description | Default | 338 | | ---------- | -------------------------------------------------------------------------------- | ---------------------------- | 339 | | `data` | The data to send. | | 340 | | `dataSize` | The number of bytes to transmit. | | 341 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 342 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 343 | | `args` | Optional argument to pass to the callback. | **NULL** | 344 | | `rai` | The release assistance information. | **WALTER_MODEM_RAI_NO_INFO** | 345 | | `socketId` | The id of the socket to close or **-1 to re-use the last one.** | **-1** | 346 | 347 | 348 | 349 | #### Returns 350 | 351 | `bool` 352 | True on success, False otherwise. 353 | 354 | --- 355 | 356 | ### `closeSocket()` 357 | 358 | Close a socket connection. 359 | 360 | > [!WARNING] 361 | > Sockets can only be **closed** when they are **suspended or inactive**. 362 | 363 | #### Example 364 | 365 | 366 | 367 | ##### **Arduino** 368 | 369 | ```cpp 370 | if(modem.closeSocket()) { 371 | Serial.printf("socket: Successfully closed the socket\n"); 372 | } else { 373 | Serial.printf("socket: Could not close the socket\n"); 374 | } 375 | ``` 376 | 377 | ##### **ESP-IDF** 378 | 379 | ```cpp 380 | if(modem.closeSocket()) { 381 | ESP_LOGI("socket", "Successfully closed the socket"); 382 | } else { 383 | ESP_LOGI("socket", "Could not close the socket"); 384 | } 385 | ``` 386 | 387 | 388 | 389 | #### Params 390 | 391 | 392 | 393 | ##### **Arduino** 394 | 395 | | Param | Description | Default | 396 | | ---------- | -------------------------------------------------------------------------------- | -------- | 397 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 398 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 399 | | `args` | Optional argument to pass to the callback. | **NULL** | 400 | | `socketId` | The id of the socket to close or **-1 to re-use the last one.** | **-1** | 401 | 402 | ##### **ESP-IDF** 403 | 404 | | Param | Description | Default | 405 | | ---------- | -------------------------------------------------------------------------------- | -------- | 406 | | `rsp` | Pointer to a modem response structure to save the result of the command in. | **NULL** | 407 | | `cb` | Optional callback argument, when not NULL this function will return immediately. | **NULL** | 408 | | `args` | Optional argument to pass to the callback. | **NULL** | 409 | | `socketId` | The id of the socket to close or **-1 to re-use the last one.** | **-1** | 410 | 411 | 412 | 413 | #### Returns 414 | 415 | `bool` 416 | True on success, False otherwise. 417 | 418 | --- 419 | 420 | ## Enums 421 | 422 | ### `WalterModemSocketProto` 423 | 424 | The protocol that us used by the socket. 425 | 426 | 427 | 428 | #### **Arduino** 429 | 430 | > **WALTER_MODEM_SOCKET_PROTO_TCP** = `0` \ 431 | > Use the TCP protocol for the socket \ 432 | > **WALTER_MODEM_SOCKET_PROTO_UDP** = `1` \ 433 | > Use the UDP protocol for the socket 434 | 435 | #### **ESP-IDF** 436 | 437 | > **WALTER_MODEM_SOCKET_PROTO_TCP** = `0` \ 438 | > Use the TCP protocol for the socket \ 439 | > **WALTER_MODEM_SOCKET_PROTO_UDP** = `1` \ 440 | > Use the UDP protocol for the socket 441 | 442 | 443 | 444 | ### `WalterModemSocketAcceptAnyRemote` 445 | 446 | Possible methodologies on how a socket handles data from other hosts 447 | besides the IP-address and remote port it is configured for. 448 | 449 | 450 | 451 | #### **Arduino** 452 | 453 | > **WALTER_MODEM_ACCEPT_ANY_REMOTE_DISABLED** = `0`\ 454 | > Do not accepty any remote data \ 455 | > **WALTER_MODEM_ACCEPT_ANY_REMOTE_RX_ONLY** = `1`\ 456 | > Only acccept read \ 457 | > **WALTER_MODEM_ACCEPT_ANY_REMOTE_RX_AND_TX** = `2` \ 458 | > Accept read write from remote 459 | 460 | #### **ESP-IDF** 461 | 462 | > **WALTER_MODEM_ACCEPT_ANY_REMOTE_DISABLED** = `0`\ 463 | > Do not accepty any remote data \ 464 | > **WALTER_MODEM_ACCEPT_ANY_REMOTE_RX_ONLY** = `1`\ 465 | > Only acccept read \ 466 | > **WALTER_MODEM_ACCEPT_ANY_REMOTE_RX_AND_TX** = `2` \ 467 | > Accept read write from remote 468 | 469 | 470 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/setup/arduino.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | This guide will walk you through installing the Walter Modem library, 4 | selecting the right board settings, 5 | and running example sketches to get your modem up and running. 6 | 7 | > [!TIP] 8 | > If you haven't set up the Arduino IDE yet, 9 | > go through [Arduino Setup Guide](/developer-toolchains/arduino.md) first. 10 | 11 | ## Guide 12 | 13 | ### 1. Installing the Walter Modem Library 14 | 15 | The Walter modem library can be easily installed 16 | via the built-in Arduino Library Manager: 17 | 18 | 1. Open the Arduino IDE. 19 | 2. Navigate to **Tools > Manage Libraries…** 20 | 3. In the search field, type `WalterModem`. 21 | 4. Select the Walter modem library from the list and click **Install**. 22 | 23 | ![Arduino Library Manager](img/arduino_library_manager.png) 24 | 25 | ### 2. Opening and Running an Example 26 | 27 | Once the library is installed, you can explore the provided examples: 28 | 29 | 1. Open the **Library Manager** in the Arduino IDE. 30 | 2. Search for **WalterModem** and select it. 31 | 3. Click on the **three dots** in the upper right corner. 32 | 4. Hover over **Examples**, then choose one from the list. 33 | 5. The selected example will open in a new sketch window. 34 | 35 | ![Arduino Examples](img/arduino_examples.png) 36 | 37 | ### 3. Board Selection and Configuration 38 | 39 | Before uploading your sketch, 40 | ensure that your board is properly selected and configured: 41 | 42 | 1. Click the board selection button in the top left corner of the Arduino IDE. 43 | 2. In the search bar, type `DPTechnics Walter` and select the board. 44 | 45 | ![Board Selection](img/board_selection.png) 46 | 47 | ![Board Selection Screen](img/board_selection_screen.png) 48 | 49 | 3. Ensure the partition scheme under **Flash Size** is set to: 50 | (128Mb APP/12.5MB FATFS), this is required to allow mmodem firmware updates. 51 | 52 | ### 4. Running the Sketch 53 | 54 | With the board configured and the example open: 55 | 56 | 1. Click the **Upload** button in the Arduino IDE. 57 | 2. Wait for the sketch to compile and upload to the board. 58 | 3. Open the Serial Monitor to view output 59 | and confirm that the modem connects to the internet. 60 | 61 | ## Additional Resources 62 | 63 | - **Library Source Code:** 64 | [GitHub Repository](https://github.com/QuickSpot/walter-arduino) 65 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/setup/esp-idf.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | This guide will walk you through installing the Walter Modem library for ESP-IDF. 4 | 5 | > [!TIP] 6 | > If you haven't set up the ESP-IDF dev environment yet, go through the 7 | > [ESP-IDF Toolchain Setup](/developer-toolchains/esp-idf.md) first 8 | 9 | ## Guide 10 | 11 | ### 1. Create a new project 12 | 13 | To create a new project, open the VS Code command palette (Quickmenu) and select:\ 14 | `>ESP-IDF: Create project from Extension Template` 15 | 16 | > [!WARNING] 17 | > When using the walter modem all implementation files (`.c`, `.cpp`) should have the `.cpp` extension. 18 | > -> not `main.c` but `main.cpp` 19 | 20 | Then select `template-app` as your starter project. 21 | 22 | ### 2. Installing the Walter Modem Component 23 | 24 | > [!WARNING] 25 | > Run all `idf.py` commands inside the ESP-IDF Terminal. 26 | 27 | Open the ESP-IDF Terminal from the VS Code command palette: 28 | `>ESP-IDF: Open ESP-IDF Terminal` and run the following command: 29 | 30 | ```console 31 | idf.py add-dependency "dptechnics/walter-modem^1.1.3" 32 | ``` 33 | 34 | > [!note] 35 | > Make sure to check the version number 36 | 37 | ### 3. Setting the Device Target 38 | 39 | After installing the Walter Modem extension, 40 | the **Device Target** needs to be set to **esp32s3** 41 | *(This needs to be done for each project)* 42 | 43 | Set this using the VSCode quickmenu command: 44 | `>ESP-IDF: Set Espressif Device Target` 45 | 46 | > [!NOTE] 47 | > If you want to use youre own `fork` or use the `DEV` version of waltermodem, 48 | > you can use the following snippet inside `idf_component.yml`. 49 | > 50 | > You can also specify the branch inside the version tag. 51 | > 52 | > ```yml 53 | > dependencies: 54 | > dptechnics/walter-modem: 55 | > version: "*" 56 | > git: "https://github.com/QuickSpot/walter-esp-idf.git" 57 | > ``` 58 | 59 | ## Additional Resources 60 | 61 | - **Library Source Code:** 62 | [GitHub Repository](https://github.com/QuickSpot/walter-esp-idf) 63 | -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/setup/img/arduino_examples.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/walter-modem/arduino_esp-idf/setup/img/arduino_examples.png -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/setup/img/arduino_library_manager.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/walter-modem/arduino_esp-idf/setup/img/arduino_library_manager.png -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/setup/img/board_selection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/walter-modem/arduino_esp-idf/setup/img/board_selection.png -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/setup/img/board_selection_screen.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/walter-modem/arduino_esp-idf/setup/img/board_selection_screen.png -------------------------------------------------------------------------------- /walter-modem/arduino_esp-idf/setup/setup.md: -------------------------------------------------------------------------------- 1 | ## _Walter Modem Library / Arduino & ESP-IDF /_ Setup 2 | 3 | - [Arduino](/walter-modem/arduino_esp-idf/setup/arduino.md) 4 | - [ESP-IDF](/walter-modem/arduino_esp-idf/setup/esp-idf.md) 5 | -------------------------------------------------------------------------------- /walter-modem/micropython/img/thonny-lib-open.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/walter-modem/micropython/img/thonny-lib-open.png -------------------------------------------------------------------------------- /walter-modem/micropython/img/thonny-new-dir.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/walter-modem/micropython/img/thonny-new-dir.png -------------------------------------------------------------------------------- /walter-modem/micropython/img/thonny-upload-to-lib.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/QuickSpot/walter-documentation/ed859d7e5ee6fb9e9169974d4c156a94e9849cd8/walter-modem/micropython/img/thonny-upload-to-lib.png -------------------------------------------------------------------------------- /walter-modem/micropython/micropython.md: -------------------------------------------------------------------------------- 1 | ## _Walter Modem Library /_ Micropython 2 | 3 | - [Setup](/walter-modem/micropython/setup.md) 4 | - [API Reference](/walter-modem/micropython/reference/reference.md) 5 | - [Common](/walter-modem/micropython/reference/common.md) 6 | - [SIM & Network](/walter-modem/micropython/reference/sim_and_network.md) 7 | - [PDP Context Management](/walter-modem/micropython/reference/pdp_ctx_management.md) 8 | - [GNSS](/walter-modem/micropython/reference/gnss.md) 9 | - [Sockets](/walter-modem/micropython/reference/sockets.md) 10 | - [HTTP](/walter-modem/micropython/reference/http.md) 11 | - [MQTT](/walter-modem/micropython/reference/mqtt.md) 12 | - [Sleep](/walter-modem/micropython/reference/sleep.md) 13 | - [TLS & Certificates](/walter-modem/micropython/reference/tls_and_certificates.md) 14 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/common.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [reset](#reset) 4 | - [check_comm](#check_comm) 5 | - [get_clock](#get_clock) 6 | - [config_cme_error_reports](#config_cme_error_reports) 7 | - [config_cereg_reports](#config_cereg_reports) 8 | 9 | ## Enums Overview 10 | 11 | - [WalterModemCMEErrorReportsType](#waltermodemcmeerrorreportstype) 12 | - [WalterModemCEREGReportsType](#waltermodemceregreportstype) 13 | - [WalterModemOpState](#waltermodemopstate) 14 | 15 | --- 16 | 17 | ## Methods 18 | 19 | ### `reset` 20 | 21 | Physically reset the modem and wait for it to start. 22 | All connections will be lost when this function is called. 23 | 24 | > [!NOTE] 25 | > The function will fail when the modem doesn't start after the reset. 26 | 27 | #### Example 28 | 29 | ```py 30 | if not await modem.reset(): 31 | print('Failed to reset modem') 32 | ``` 33 | 34 | #### Params 35 | 36 | | Param | Description | Default | 37 | | ----- | --------------------------------------- | -------- | 38 | | `rsp` | Reference to a modem response instance. | **None** | 39 | 40 | #### Returns 41 | 42 | `bool` 43 | True on success, False otherwise. 44 | 45 | --- 46 | 47 | ### `soft_reset` 48 | 49 | Perform a soft reset on the modem, wait for it to complete. 50 | 51 | > [!NOTE] 52 | > The method will fail when the modem doesn't reset. 53 | 54 | #### Example 55 | 56 | ```py 57 | if not await modem.soft_reset(): 58 | print('Failed to soft reset modem') 59 | ``` 60 | 61 | #### Returns 62 | 63 | `bool` 64 | True on success, False otherwise. 65 | 66 | --- 67 | 68 | ### `check_comm` 69 | 70 | Sends the 'AT' command to check if the modem responds with 'OK', 71 | verifying communication between the ESP32S3 and the modem. 72 | 73 | #### Example 74 | 75 | ```py 76 | if await modem.check_comm(): 77 | print('Modem communication successfull') 78 | ``` 79 | 80 | #### Params 81 | 82 | | Param | Description | Default | 83 | | ----- | --------------------------------------- | -------- | 84 | | `rsp` | Reference to a modem response instance. | **None** | 85 | 86 | #### Returns 87 | 88 | `bool` 89 | True on success, False otherwise. 90 | 91 | --- 92 | 93 | ### `get_clock` 94 | 95 | Retrieves the current time and date from the modem. 96 | 97 | #### Example 98 | 99 | ```py 100 | modem_rsp = ModemRsp() 101 | 102 | if await modem.get_clock(rsp=modem_rsp): 103 | print(modem_rsp.clock) 104 | else: 105 | print('Failed to get modem clock') 106 | 107 | ``` 108 | 109 | #### Params 110 | 111 | | Param | Description | Default | 112 | | ----- | --------------------------------------- | -------- | 113 | | `rsp` | Reference to a modem response instance. | **None** | 114 | 115 | #### Returns 116 | 117 | `bool` 118 | True on success, False otherwise. 119 | 120 | --- 121 | 122 | ### `config_cme_error_reports` 123 | 124 | Configures the CME error report type. 125 | By default, errors are enabled and numeric. 126 | 127 | > [!WARNING] 128 | > Changing this may affect error reporting. 129 | 130 | #### Example 131 | 132 | ```py 133 | if not await modem.config_cme_error_reports(reports_type=WalterModemCMEErrorReportsType.VERBOSE): 134 | print('Failed to configure CME error reports') 135 | ``` 136 | 137 | #### Params 138 | 139 | | Param | Description | Default | 140 | | -------------- | ------------------------------------------------------------- | ------------------------------------------ | 141 | | `reports_type` | The [CME error report type](#waltermodemcmeerrorreportstype). | **WalterModemCMEErrorReportsType.NUMERIC** | 142 | | `rsp` | Reference to a modem response instance. | **None** | 143 | 144 | #### Returns 145 | 146 | `bool` 147 | True on success, False otherwise. 148 | 149 | --- 150 | 151 | ### `config_cereg_reports` 152 | 153 | Configures the CEREG status report type. 154 | By default, reports are enabled with minimal operational info. 155 | 156 | > [!WARNING] 157 | > Changing this may affect library functionality. 158 | 159 | #### Example 160 | 161 | ```py 162 | if not await modem.config_cereg_reports(reports_type=WalterModemCEREGReportsType.ENABLED): 163 | print('Failed to config CEREg reports') 164 | ``` 165 | 166 | #### Params 167 | 168 | | Param | Description | Default | 169 | | -------------- | -------------------------------------------------------------- | --------------------------------------- | 170 | | `reports_type` | The [CEREG status reports type](#waltermodemceregreportstype). | **WalterModemCEREGReportsType.ENABLED** | 171 | | `rsp` | Reference to a modem response instance. | **None** | 172 | 173 | #### Returns 174 | 175 | `bool` 176 | True on success, False otherwise. 177 | 178 | --- 179 | 180 | ## Enums 181 | 182 | ### `WalterModemCMEErrorReportsType` 183 | 184 | Modem CME error reporting methods. 185 | 186 | > **OFF** = `0` \ 187 | > No error reporting. \ 188 | > **NUMERIC** = `1` \ 189 | > Numeric error codes for reporting. \ 190 | > **VERBOSE** = `2` \ 191 | > Detailed verbose error messages. 192 | 193 | ### `WalterModemCEREGReportsType` 194 | 195 | CEREG unsolicited reporting methods. 196 | 197 | > **OFF** = `0` \ 198 | > No unsolicited reporting. \ 199 | > **ENABLED** = `1` \ 200 | > Unsolicited reporting enabled. \ 201 | > **ENABLED_WITH_LOCATION** = `2` \ 202 | > Unsolicited reporting with location information. \ 203 | > **ENABLED_WITH_LOCATION_EMM_CAUSE** = `3` \ 204 | > Unsolicited reporting with location and EMM cause. \ 205 | > **ENABLED_UE_PSM_WITH_LOCATION** = `4` \ 206 | > Unsolicited reporting with UE PSM and location. \ 207 | > **ENABLED_UE_PSM_WITH_LOCATION_EMM_CAUSE** = `5` \ 208 | > Unsolicited reporting with UE PSM, location, and EMM cause. 209 | 210 | ### `WalterModemOpState` 211 | 212 | Modem operational modes. 213 | 214 | > **MINIMUM** = `0` \ 215 | > Minimal operational mode. \ 216 | > **FULL** = `1` \ 217 | > Full operational mode. \ 218 | > **NO_RF** = `4` \ 219 | > No RF (Radio Frequency) operation. \ 220 | > **MANUFACTURING** = `5` \ 221 | > Manufacturing mode for testing and diagnostics. 222 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/gnss.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [config_gnss](#config_gnss) 4 | - [get_gnss_assistance_status](#get_gnss_assistance_status) 5 | - [update_gnss_assistance](#update_gnss_assistance) 6 | - [perform_gnss_action](#perform_gnss_action) 7 | - [wait_for_gnss_fix](#wait_for_gnss_fix) 8 | 9 | ## Enums Overview 10 | 11 | --- 12 | 13 | ## Methods 14 | 15 | ### `config_gnss` 16 | 17 | Configures Walter's GNSS receiver with persistent settings that 18 | may need to be reset after a modem firmware upgrade.\ 19 | Can also adjust sensitivity mode between fixes. 20 | 21 | > [!TIP] 22 | > Recommended to run at least once before using GNSS. 23 | 24 | #### Example 25 | 26 | ```py 27 | if not await modem.config_gnss(): 28 | print('Failed to configure GNSS subsystem') 29 | ``` 30 | 31 | #### Params 32 | 33 | | Param | Description | Default | 34 | | ----------- | -------------------------------------------------- | --------------------------------------------- | 35 | | `sens_mode` | The [sensitivity mode](#waltermodemgnsssensmode). | **WalterModemGNSSSensMode.HIGH** | 36 | | `acq_mode` | The [acquisition mode](#waltermodemgnssacqmode). | **WalterModemGNSSAcqMode.COLD_WARM_START** | 37 | | `loc_mode` | The [GNSS location mode](#waltermodemgnsslocmode). | **WalterModemGNSSLocMode.ON_DEVICE_LOCATION** | 38 | | `rsp` | Reference to a modem response instance. | **None** | 39 | 40 | #### Returns 41 | 42 | `bool` 43 | True on success, False otherwise. 44 | 45 | --- 46 | 47 | ### `get_gnss_assistance_status` 48 | 49 | Retrieves the status of the assistance data 50 | currently loaded in the GNSS subsystem. 51 | 52 | #### Example 53 | 54 | ```py 55 | if not await modem.get_gnss_assistance_status(rsp=modem_rsp): 56 | print('Failed to request GNSS assistance status') 57 | ``` 58 | 59 | #### Params 60 | 61 | | Param | Description | Default | 62 | | ----- | --------------------------------------- | -------- | 63 | | `rsp` | Reference to a modem response instance. | **None** | 64 | 65 | #### Returns 66 | 67 | `bool` 68 | True on success, False otherwise. 69 | 70 | --- 71 | 72 | ### `update_gnss_assistance` 73 | 74 | Connects to the cloud to download and update the GNSS subsystem 75 | with the requested assistance data. 76 | 77 | > [!TIP] 78 | > Real-time ephemeris is the most efficient type. 79 | 80 | #### Example 81 | 82 | ```py 83 | if not await modem.update_gnss_assistance(): 84 | print('Failed to update almanac data') 85 | ``` 86 | 87 | #### Params 88 | 89 | | Param | Description | Default | 90 | | ------ | ----------------------------------------------------------------------------- | ---------------------------------------------------- | 91 | | `type` | The [type of GNSS assistance data](#waltermodemgnssassistancetype) to update. | **WalterModemGNSSAssistanceType.REALTIME_EPHEMERIS** | 92 | | `rsp` | Reference to a modem response instance. | **None** | 93 | 94 | #### Returns 95 | 96 | `bool` 97 | True on success, False otherwise. 98 | 99 | --- 100 | 101 | ### `perform_gnss_action` 102 | 103 | Programs the GNSS subsystem to perform a specified action. 104 | 105 | #### Example 106 | 107 | ```py 108 | if not await modem.perform_gnss_action( 109 | action=WalterModemGNSSAction.GET_SINGLE_FIX, 110 | rsp=modem_rsp 111 | ): 112 | print('Failed to request GNSS fix', 113 | WalterModemCMEError.get_value_name(modem_rsp.cme_error)) 114 | ``` 115 | 116 | #### Params 117 | 118 | | Param | Description | Default | 119 | | -------- | ----------------------------------------------------------------------- | ---------------------------------------- | 120 | | `action` | The [action for the GNSS subsystem](#waltermodemgnssaction) to perform. | **WalterModemGNSSAction.GET_SINGLE_FIX** | 121 | | `rsp` | Reference to a modem response instance. | **None** | 122 | 123 | #### Returns 124 | 125 | `bool` 126 | True on success, False otherwise. 127 | 128 | --- 129 | 130 | ### `wait_for_gnss_fix` 131 | 132 | Waits for a gnss fix before then returning it. 133 | 134 | #### Example 135 | 136 | ```py 137 | gnss_fix = await modem.wait_for_gnss_fix() 138 | ``` 139 | 140 | #### Returns 141 | 142 | `ModemGNSSFix` 143 | 144 | --- 145 | 146 | ## Enums 147 | 148 | ### `WalterModemGNSSSensMode` 149 | 150 | The possible sensitivity settings use by Walter's GNSS receiver. 151 | This sets the amount of time that the receiver is actually on. 152 | 153 | More sensitivity requires more power. 154 | 155 | > **LOW** = `1` \ 156 | > **MEDIUM** = `2` \ 157 | > **HIGH** = `3` 158 | 159 | ### `WalterModemGNSSAcqMode` 160 | 161 | The possible GNSS acquisition modes. 162 | 163 | When no ephemerides are available and/or the time is not known 164 | cold start will be used automatically. 165 | 166 | > **COLD_WARM_START** = `0` \ 167 | > Walter has no clue where he is on earth. \ 168 | > **HOT_START** = `1` \ 169 | > Walter must know where he is within 100km. 170 | 171 | ### `WalterModemGNSSLocMode` 172 | 173 | The GNSS location modus. 174 | 175 | > **ON_DEVICE_LOCATION** = `0` \ 176 | > The GNSS sybsystem will compute 177 | > position and speed and estimate the error on these parameters. 178 | 179 | ### `WalterModemGNSSAssistanceType` 180 | 181 | Types of GNSS assistance data used to improve positioning performance. 182 | 183 | > **ALMANAC** = `0` \ 184 | > Long-term orbital data providing coarse satellite positions and health status. \ 185 | > **REALTIME_EPHEMERIS** = `1` \ 186 | > Real-time satellite position and velocity data for immediate accuracy. \ 187 | > **PREDICTED_EPHEMERIS** = `2` \ 188 | > Forecasted satellite position data for faster cold starts without a live connection. 189 | 190 | ### `WalterModemGNSSAction` 191 | 192 | Supported actions that Walter's GNSS can execute. 193 | 194 | > **GET_SINGLE_FIX** = `0` \ 195 | > **CANCEL** = `1` 196 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/http.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [http_config_profile](#http_config_profile) 4 | - [http_send](#http_send) 5 | - [http_query](#http_query) 6 | - [http_did_ring](#http_did_ring) 7 | 8 | ## Enums Overview 9 | 10 | - [WalterModemHttpSendCmd](#waltermodemhttpsendcmd) 11 | - [WalterModemHttpQueryCmd](#waltermodemhttpquerycmd) 12 | - [WalterModemHttpPostParam](#waltermodemhttppostparam) 13 | 14 | --- 15 | 16 | ## Methods 17 | 18 | ### `http_config_profile` 19 | 20 | Configure a HTTP profile. 21 | 22 | This function will configure an HTTP profile 23 | with parameters such as the server name and auth info. 24 | 25 | The profile information is stored persistently in the modem, it thus is possible 26 | to store connection information once to prepare all settings, 27 | and later rely on this preconfigured profile in the modem without the need to 28 | set the parameters again in the actual code used in production. 29 | 30 | > [!TIP] 31 | > You first need to call 32 | > [`tls_config_profile`](/walter-modem/micropython/reference/tls_and_certificates.md#tls_config_profile) 33 | 34 | #### Example 35 | 36 | ```py 37 | HTTP_PROFILE = 1 38 | TLS_PROFILE = 1 39 | 40 | if await modem.http_config_profile( 41 | profile_id=HTTP_PROFILE, 42 | server_address="tls13.akamai.io", 43 | port=443, 44 | tls_profile_id=TLS_PROFILE 45 | ): 46 | print('Successfully configured the HTTP profile') 47 | else: 48 | print('Failed to configure HTTP profile') 49 | 50 | ``` 51 | #### Params 52 | 53 | | Param | Description | Default | 54 | | ---------------- | ------------------------------------------------ | --------- | 55 | | `profile_id` | HTTP profile id **(0, 1 or 2)**. | | 56 | | `server_address` | The server name to connect to. | | 57 | | `port` | The port of the server to connect to. | **80** | 58 | | `use_basic_auth` | Set true to use basic auth and send username/pw. | **False** | 59 | | `auth_user` | Username. | **""** | 60 | | `auth_pass` | Password. | **""** | 61 | | `tls_profile_id` | If not 0, TLS is used with the given profile. | **None** | 62 | | `rsp` | Reference to a modem response instance. | **None** | 63 | 64 | #### Returns 65 | 66 | `bool` 67 | True on success, False otherwise. 68 | 69 | --- 70 | 71 | ### `http_send` 72 | 73 | Perform a http **POST** or **PUT** request. 74 | 75 | > [!NOTE] 76 | > No need to first open the connection with the buggy httpConnect command 77 | unless you need TLS + a private key. 78 | 79 | #### Example 80 | 81 | ```py 82 | modem_rsp = ModemRsp() 83 | data_buf = bytearray(8) 84 | 85 | if await modem.http_send( 86 | profile_id=HTTP_PROFILE, 87 | uri='/', 88 | data=data_buf, 89 | send_cmd=WalterModemHttpSendCmd.POST, 90 | post_param=WalterModemHttpPostParam.OCTET_STREAM, 91 | rsp=modem_rsp 92 | ): 93 | print('HTTP query performed') 94 | else: 95 | print('HTTP query failed') 96 | ``` 97 | #### Params 98 | 99 | | Param | Description | Default | 100 | | ------------ | --------------------------------------------------------- | ---------------------------------------- | 101 | | `profile_id` | The profile id **(0, 1 or 2)** of the HTTP context. | | 102 | | `uri` | The URI. | | 103 | | `data` | Data to be sent to the server. | | 104 | | `send_cmd` | POST or PUT [command](#waltermodemhttpsendcmd). | **WalterModemHttpSendCmd.POST** | 105 | | `post_param` | [Content type](#waltermodemhttppostparam) *(enum value)*. | **WalterModemHttpPostParam.UNSPECIFIED** | 106 | | `rsp` | Reference to a modem response instance. | **None** | 107 | 108 | #### Returns 109 | 110 | `bool` 111 | True on success, False otherwise. 112 | 113 | --- 114 | 115 | ### `http_query` 116 | 117 | Perform a http **GET**, **DELETE** or **HEAD** request. 118 | 119 | > [!NOTE] 120 | > No need to first open the connection with the buggy httpConnect command 121 | unless you need TLS + a private key. 122 | 123 | #### Example 124 | 125 | ```py 126 | modem_rsp = ModemRsp() 127 | 128 | if await modem.http_query( 129 | profile_id=HTTP_PROFILE, 130 | uri='/', 131 | query_cmd=WalterModemHttpQueryCmd.GET, 132 | rsp=modem_rsp 133 | ): 134 | print('HTTP query performed') 135 | else: 136 | print('HTTP query failed') 137 | ``` 138 | 139 | #### Params 140 | 141 | | Param | Description | Default | 142 | | ------------------- | --------------------------------------------------------------- | ------------------------------- | 143 | | `profile_id` | The profile id (0, 1 or 2) of the HTTP context. | | 144 | | `uri` | The URI. | | 145 | | `query_cmd` | GET, DELETE, or HEAD [command](#waltermodemhttpquerycmd). | **WalterModemHttpQueryCmd.GET** | 146 | | `extra_header_line` | Optional additional lines to be placed in the request's header. | **None** | 147 | | `rsp` | Reference to a modem response instance. | **None** | 148 | 149 | #### Returns 150 | 151 | `bool` 152 | True on success, False otherwise. 153 | 154 | --- 155 | 156 | ### `http_did_ring` 157 | 158 | Fetch http response to earlier http request, if any. 159 | 160 | #### Example 161 | 162 | ```py 163 | modem_rsp = ModemRsp() 164 | 165 | while not await modem.http_did_ring(profile_id=HTTP_PROFILE, rsp=modem_rsp): 166 | if modem_rsp.result not in (WalterModemState.OK, WalterModemState.AWAITING_RING): 167 | print(f"Error: {modem_rsp.result}") 168 | break 169 | await asyncio.sleep(1) 170 | 171 | if modem_rsp.http_response is not None: 172 | print(f'HTTP status code: {modem_rsp.http_response.http_status}') 173 | print(f'HTTP content type: {modem_rsp.http_response.content_type}') 174 | print(f'HTTP: {modem_rsp.http_response.data}') 175 | ``` 176 | 177 | #### Params 178 | 179 | | Param | Description | Default | 180 | | ------------ | --------------------------------------- | -------- | 181 | | `profile_id` | Profile for which to get the response. | | 182 | | `rsp` | Reference to a modem response instance. | **None** | 183 | 184 | #### Returns 185 | 186 | `bool` 187 | True on success, False otherwise. 188 | 189 | --- 190 | 191 | ## Enums 192 | 193 | ### `WalterModemHttpSendCmd` 194 | 195 | The possible commands for a HTTP send operation. 196 | 197 | > **POST** = `0` \ 198 | > Perform a POST request \ 199 | > **PUT** = `1` \ 200 | > Perform PUT request 201 | 202 | ### `WalterModemHttpQueryCmd` 203 | 204 | The possible commands for a HTTP query operation. 205 | 206 | > **GET** = `0` \ 207 | > Perform a GET request \ 208 | > **HEAD** = `1` \ 209 | > Perform a HEAD request \ 210 | > **DELETE** = `2` \ 211 | > Perform a DELETE request 212 | 213 | ### `WalterModemHttpPostParam` 214 | 215 | The possible post params for a HTTP send operation. 216 | 217 | > **URL_ENCODED** = `0` \ 218 | > Param type is encoded in the url \ 219 | > **TEXT_PLAIN** = `1` \ 220 | > Param is plain text \ 221 | > **OCTET_STREAM** = `2` \ 222 | > Param is an octet/byte stream \ 223 | > **FORM_DATA** = `3` \ 224 | > Param is form data \ 225 | > **JSON** = `4` \ 226 | > Param is JSON \ 227 | > **UNSPECIFIED** = `99` \ 228 | > Param is unspecified 229 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/mqtt.md: -------------------------------------------------------------------------------- 1 | # MQTT 2 | 3 | ## Methods Overview 4 | 5 | - [mqtt_config](#mqtt_config) 6 | - [mqtt_connect](#mqtt_connect) 7 | - [mqtt_disconnect](#mqtt_disconnect) 8 | - [mqtt_subscribe](#mqtt_subscribe) 9 | - [mqtt_publish](#mqtt_publish) 10 | - [mqtt_did_ring](#mqtt_did_ring) 11 | 12 | --- 13 | 14 | ## Methods 15 | 16 | ### `mqtt_config` 17 | 18 | Configure the MQTT client without connecting. 19 | 20 | #### Example 21 | 22 | ```py 23 | MQTT_USERNAME = '' 24 | MQTT_PASSWORD = '' 25 | TLS_PROFILE_ID = 1 26 | 27 | if await modem.mqtt_config( 28 | user_name=MQTT_USERNAME, 29 | password=MQTT_PASSWORD, 30 | tls_profile_id=TLS_PROFILE_ID 31 | ): 32 | print('Successfully configured MQTT') 33 | else: 34 | print('Could not configure MQTT') 35 | ``` 36 | #### Params 37 | 38 | | Param | Description | Default | 39 | | ------------------------ | --------------------------------------------------- | ---------- | 40 | | `client_id` | MQTT client ID to use. | device MAC | 41 | | `user_name` | Optional username for authentication. | **""** | 42 | | `password` | Optional password for authentication. | **""** | 43 | | `tls_profile_id` | Optional TLS profile ID to use. | **None** | 44 | | `library_message_buffer` | Size of the library's internal MQTT message buffer. | **16** | 45 | | `rsp` | Reference to a modem response instance. | **None** | 46 | 47 | > [!WARNING] 48 | > The **library_message_bugger** stores metadata for received messages 49 | > but does not hold their payloads. \ 50 | > The modem itself supports up to 100 messages, however, 51 | > significantly increasing this buffer may consume excessive memory 52 | > and is not recommended 53 | 54 | #### Returns 55 | 56 | `bool` 57 | True on success, False otherwise. 58 | 59 | --- 60 | 61 | ### `mqtt_connect` 62 | 63 | Initialise MQTT and establish a connection. 64 | 65 | #### Example 66 | 67 | ```py 68 | if await modem.mqtt_connect( 69 | server_name='test.mosquitto.org', 70 | port=1883 71 | ): 72 | print('MQTT connection successfull') 73 | else: 74 | print('MQTT connection failed') 75 | ``` 76 | 77 | #### Params 78 | 79 | | Param | Description | Default | 80 | | ------------- | --------------------------------------- | -------- | 81 | | `server_name` | MQTT broker hostname. | | 82 | | `port` | Port to connect to. | | 83 | | `keep_alive` | Maximum keepalive time *(in seconds)*. | 60 | 84 | | `rsp` | Reference to a modem response instance. | **None** | 85 | 86 | #### Returns 87 | 88 | `bool` 89 | True on success, False otherwise. 90 | 91 | --- 92 | 93 | ### `mqtt_disconnect` 94 | 95 | Disconnect from an MQTT broker. 96 | 97 | #### Example 98 | 99 | ```py 100 | await modem.mqtt_disconnect() 101 | ``` 102 | 103 | #### Params 104 | 105 | | Param | Description | Default | 106 | | ----- | --------------------------------------- | -------- | 107 | | `rsp` | Reference to a modem response instance. | **None** | 108 | 109 | #### Returns 110 | 111 | `bool` 112 | True on success, False otherwise. 113 | 114 | --- 115 | 116 | ### `mqtt_subscribe` 117 | 118 | Subscribe to a MQTT topic. 119 | 120 | This function subscribes to a given topic using the connection established 121 | earlier through [`mqtt_connect`](#mqtt_connect). 122 | 123 | #### Example 124 | 125 | ```py 126 | if await modem.mqtt_subscribe( 127 | 128 | ): 129 | print('subscribed to topic waltertopic') 130 | else: 131 | print('subscribe failed') 132 | ``` 133 | 134 | #### Params 135 | 136 | | Param | Description | Default | 137 | | ------- | ------------------------------------------------------------------------ | -------- | 138 | | `topic` | Topic to subscribe to. | | 139 | | `qos` | Quality of Service (0: at least once, 1: at least once, 2: exactly once) | **1** | 140 | | `rsp` | Reference to a modem response instance. | **None** | 141 | 142 | #### Returns 143 | 144 | `bool` 145 | True on success, False otherwise. 146 | 147 | --- 148 | 149 | ### `mqtt_publish` 150 | 151 | Publish something through MQTT. 152 | 153 | This function publishes the passed data on the given mqtt topic using the 154 | connection established earlier through [`mqtt_connect`](#mqttconnect). 155 | 156 | #### Example 157 | 158 | ```py 159 | if await modem.mqtt_publish( 160 | topic=topic, 161 | data='Hello from Walter' 162 | ): 163 | print('Message Published') 164 | else: 165 | print('Failed to publish message') 166 | ``` 167 | 168 | #### Params 169 | 170 | | Param | Description | Default | 171 | | ------- | -------------------------------------------------------------------- | -------- | 172 | | `topic` | Topic to publish on. | | 173 | | `data` | The data to publish | | 174 | | `qos` | QoS: 0 = at most once, 1 = at least once, 2 = exactly once received. | **1** | 175 | | `rsp` | Reference to a modem response instance. | **None** | 176 | 177 | #### Returns 178 | 179 | `bool` 180 | True on success, False otherwise. 181 | 182 | --- 183 | 184 | ### `mqtt_did_ring` 185 | 186 | Poll if the modem has reported any incoming MQTT messages received on subscribed 187 | topics. 188 | 189 | > [!WARNING] 190 | > No more than 1 message with QoS 0 are stored in the buffer, 191 | > every new message with QoS 0 overwrites the previous\ 192 | > (this only applies to messages with QoS 0) 193 | 194 | #### Example 195 | 196 | ```py 197 | modem_rsp = ModemRsp() 198 | mqtt_messages = [] 199 | 200 | if await modem.mqtt_did_ring(msg_list=mqtt_messages, rsp=modem_rsp): 201 | print(f'New MQTT message (topic: {modem_rsp.mqtt_response.topic}, qos: {modem_rsp.mqtt_response.qos})') 202 | print(mqtt_messages.pop()) 203 | else: 204 | if modem_rsp.result != WalterModemState.NO_DATA: 205 | print('Fault with mqtt_did_ring: ' 206 | f'{WalterModemState.get_value_name(modem_rsp.result)}') 207 | ``` 208 | 209 | #### Params 210 | 211 | | Param | Description | Default | 212 | | ---------- | ----------------------------------------------------------- | -------- | 213 | | `msg_list` | Refence to a list where the received messages will be put. | | 214 | | `topic` | The exact topic to filter on, leave as None for all topics. | **None** | 215 | | `rsp` | Reference to a modem response instance. | **None** | 216 | 217 | #### Returns 218 | 219 | `bool` 220 | True on success, False 221 | if no message(s) arrived, error or if no message(s) are expected *(eg no ring received)*. 222 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/pdp_ctx_management.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [create_PDP_context](#create_pdp_context) 4 | - [set_PDP_auth_params](#set_pdp_auth_params) 5 | - [set_PDP_context_active](#set_pdp_context_active) 6 | - [set_network_attachment_state](#set_network_attachment_state) 7 | - [get_PDP_address](#get_pdp_address) 8 | 9 | ## Enums Overview 10 | 11 | - [WalterModemPDPAuthProtocol](#waltermodempdpauthprotocol) 12 | - [WalterModemPDPType](#waltermodempdptype) 13 | - [WalterModemPDPHeaderCompression](#waltermodempdpheadercompression) 14 | - [WalterModemPDPDataCompression](#waltermodempdpdatacompression) 15 | - [WalterModemPDPIPv4AddrAllocMethod](#waltermodempdpipv4addrallocmethod) 16 | - [WalterModemPDPRequestType](#waltermodempdprequesttype) 17 | - [WalterModemPDPPCSCFDiscoveryMethod](#waltermodempdppcscfdiscoverymethod) 18 | - [WalterModemPDPContextState](#waltermodempdpcontextstate) 19 | 20 | --- 21 | 22 | ## Methods 23 | 24 | ### `create_PDP_context` 25 | 26 | Creates a new packet data protocol (PDP). 27 | 28 | #### Example 29 | 30 | ```py 31 | CELL_APN = '' 32 | APN_USERNAME = None 33 | APN_PASSWORD = None 34 | 35 | modem_rsp = ModemRsp() 36 | 37 | if not await modem.create_PDP_context( 38 | apn=CELL_APN, 39 | rsp=modem_rsp 40 | ): 41 | print('Failed to create PDP Context') 42 | print('Successfully created PDP Context') 43 | ``` 44 | 45 | #### Params 46 | 47 | | Param | Description | Default | 48 | | ---------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- | 49 | | `context_id` | The PDP Context ID | **1** | 50 | | `apn` | The access point name. | **""** | 51 | | `pdp_type` | The [type of PDP context](#waltermodempdptype) to create. | **WalterModemPDPType.IP** | 52 | | `pdp_address` | Optional PDP address. | **None** | 53 | | `header_comp` | The [type of header compression](#waltermodempdpheadercompression) to use. | **WalterModemPDPHeaderCompression.OFF** | 54 | | `data_comp` | The [type of data compression](#waltermodempdpdatacompression) to use. | **WalterModemPDPDataCompression.OFF** | 55 | | `ipv4_alloc_method` | The [IPv4 alloction method](#waltermodempdpipv4addrallocmethod). | **WalterModemPDPIPv4AddrAllocMethod.DHCP** | 56 | | `request_type` | The [type of PDP requests](#waltermodempdprequesttype). | **WalterModemPDPRequestType.NEW_OR_HANDOVER** | 57 | | `pcscf_method` | The [method to use for P-CSCF discovery](#waltermodempdppcscfdiscoverymethod). | **WalterModemPDPPCSCFDiscoveryMethod.AUTO** | 58 | | `for_IMCN` | Set when this PDP ctx is used for IM CN signalling. | **False** | 59 | | `use_NSLPI` | Set when NSLPI is used. | **False** | 60 | | `use_secure_PCO` | Set to use secure protocol config options. | **False** | 61 | | `use_NAS_ipv4_MTU_discovery` | Set to use NAS for IPv4 MTU discovery. | **False** | 62 | | `use_local_addr_ind` | Set when local IPs are supported in the TFT. | **False** | 63 | | `use_NAS_on_IPMTU_discovery` | Set for NAS based no-IP MTU discovery. | **False** | 64 | | `rsp` | Reference to a modem response instance. | **None** | 65 | 66 | #### Returns 67 | 68 | `bool` 69 | True on success, False otherwise. 70 | 71 | --- 72 | 73 | ### `set_PDP_auth_params` 74 | 75 | Specify authentication parameters for the PDP. 76 | 77 | #### Example 78 | 79 | ```py 80 | if await modem.set_PDP_auth_params( 81 | context_id=PDP_CTX_ID, 82 | protocol=AUTH_PROTO, 83 | user_id=AUTH_USER, 84 | password=AUTH_PASS 85 | ): 86 | print('PDP context authenticated') 87 | else: 88 | print('Failed to authenticate PDP context') 89 | ``` 90 | 91 | #### Params 92 | 93 | | param | description | default | 94 | | ------------ | ---------------------------------------------------------------- | ----------------------------------- | 95 | | `context_id` | The PDP context. | **1** | 96 | | `protocol` | The used [authentication protocol](#waltermodempdpauthprotocol). | **WalterModemPDPAuthProtocol.NONE** | 97 | | `user_id` | Optional user to use for authentication. | **None** | 98 | | `password` | Optional password to use for authentication. | **None** | 99 | | `rsp` | Reference to a modem response instance. | **None** | 100 | 101 | #### Returns 102 | 103 | `bool` 104 | True on success, False otherwise. 105 | 106 | --- 107 | 108 | ### `set_PDP_context_active` 109 | 110 | Activates or deactivates a given PDP context. 111 | 112 | #### Example 113 | 114 | ```py 115 | if not await modem.set_PDP_context_active(active=False): 116 | print('Failed to deactivate last used pdp context') 117 | ``` 118 | 119 | #### Params 120 | 121 | | Param | Description | Default | 122 | | ------------ | ------------------------------------------------------ | -------- | 123 | | `active` | True to activate the PDP context, False to deactivate. | **True** | 124 | | `context_id` | The PDP context id. | **1** | 125 | | `rsp` | Reference to a modem response instance. | **None** | 126 | 127 | #### Returns 128 | 129 | `bool` 130 | True on success, False otherwise. 131 | 132 | --- 133 | 134 | ### `set_network_attachment_state` 135 | 136 | Attaches to or detaches from the currently active PDP context 137 | for packet domain service. 138 | 139 | #### Example 140 | 141 | ```py 142 | if not await modem.set_network_attachment_state(attach=True): 143 | print('Failed to attach PDP context') 144 | ``` 145 | 146 | #### Params 147 | 148 | | Param | Description | Default | 149 | | -------- | --------------------------------------- | -------- | 150 | | `attach` | True to attach, False to detach. | **True** | 151 | | `rsp` | Reference to a modem response instance. | **None** | 152 | 153 | #### Returns 154 | 155 | `bool` 156 | True on success, False otherwise. 157 | 158 | --- 159 | 160 | ### `get_PDP_address` 161 | 162 | Retrieves the list of PDP addresses for the specified PDP context ID. 163 | 164 | #### Example 165 | 166 | ```py 167 | PDP_CONTEXT_ID = 1 168 | 169 | if not await modem.get_PDP_address(context_id=PDP_CONTEXT_ID): 170 | print('Failed to get PDP addresses') 171 | ``` 172 | 173 | #### Params 174 | 175 | | Param | Description | Default | 176 | | ------------ | -------------------------------------- | -------- | 177 | | `context_id` | The PDP context id. | **1** | 178 | | `rsp` | Reference to a modem response instance | **None** | 179 | 180 | #### Returns 181 | 182 | `bool` 183 | True on success, False otherwise. 184 | 185 | --- 186 | 187 | ## Enums 188 | 189 | ### `WalterModemPDPAuthProtocol` 190 | 191 | PDP context authentication protocols. 192 | 193 | > **NONE** = `0` \ 194 | > No authentication required. \ 195 | > **PAP** = `1` \ 196 | > Password Authentication Protocol, 197 | > a simple authentication method that transmits credentials in plaintext. \ 198 | > **CHAP** = `2` \ 199 | > Uses challenge-response for safer authentication. 200 | 201 | ### `WalterModemPDPType` 202 | 203 | Supported packet data protocol types. 204 | 205 | > **X25** = `0` \ 206 | > Packet-switched data protocol used in legacy networks. \ 207 | > **IP** = `1` \ 208 | > Standard IPv4 protocol for internet communication. \ 209 | > **IPV6** = `2` \ 210 | > Next-generation IP with improved addressing. \ 211 | > **IPV4V6** = `3` \ 212 | > Supports both IPv4 and IPv6. \ 213 | > **OSPIH** = `4` \ 214 | > Obsolete packet-switched protocol. \ 215 | > **PPP** = `5` \ 216 | > Point-to-Point Protocol for direct connections. \ 217 | > **NON_IP** = `6` \ 218 | > For non-IP data transmission. 219 | 220 | ### `WalterModemPDPHeaderCompression` 221 | 222 | Supported packet data protocol header compression mechanisms. 223 | 224 | > **OFF** = `0` \ 225 | > No header compression. \ 226 | > **ON** = `1` \ 227 | > Header compression enabled. \ 228 | > **RFC1144** = `2` \ 229 | > Van Jacobson TCP/IP header compression. \ 230 | > **RFC2507** = `3` \ 231 | > IP header compression for low-bandwidth links. \ 232 | > **RFC3095** = `4` \ 233 | > ROHC (Robust Header Compression) for IP, UDP, and RTP. \ 234 | > **UNSPEC** = `99` \ 235 | > Unspecified compression method. 236 | 237 | ### `WalterModemPDPDataCompression` 238 | 239 | Supported packet data protocol data compression mechanisms. 240 | 241 | > **OFF** = `0` \ 242 | > No data compression. \ 243 | > **ON** = `1` \ 244 | > Data compression enabled. \ 245 | > **V42BIS** = `2` \ 246 | > ITU-T V.42bis data compression. \ 247 | > **V44** = `3` \ 248 | > ITU-T V.44 improved data compression. \ 249 | > **UNSPEC** = `99` \ 250 | > Unspecified compression method. 251 | 252 | ### `WalterModemPDPIPv4AddrAllocMethod` 253 | 254 | Supported packet data protocol IPv4 address allocation methods. 255 | 256 | > **NAS** = `0` \ 257 | > Address allocation by the Network Access Server. \ 258 | > **DHCP** = `1` \ 259 | > Dynamic Host Configuration Protocol for address allocation. 260 | 261 | ### `WalterModemPDPRequestType` 262 | 263 | Supported packet data protocol request types. 264 | 265 | > **NEW_OR_HANDOVER** = `0` \ 266 | > Request for a new connection or handover. \ 267 | > **EMERGENCY** = `1` \ 268 | > Emergency connection request. \ 269 | > **NEW** = `2` \ 270 | > Request for a new connection. \ 271 | > **HANDOVER** = `3` \ 272 | > Request to handover an existing connection. \ 273 | > **EMERGENCY_HANDOVER** = `4` \ 274 | > Emergency handover request. 275 | 276 | ### `WalterModemPDPPCSCFDiscoveryMethod` 277 | 278 | Supported types of P-CSCF discovery in a packet data context. 279 | 280 | > **AUTO** = `0` \ 281 | > Automatic P-CSCF discovery. \ 282 | > **NAS** = `1` \ 283 | > P-CSCF discovery by the Network Access Server. 284 | 285 | ### `WalterModemPDPContextState` 286 | 287 | PDP context states. 288 | 289 | > **FREE** = `0` \ 290 | > Free and available. \ 291 | > **RESERVED** = `1` \ 292 | > Reserved but not yet active. \ 293 | > **INACTIVE** = `2` \ 294 | > Is not in use. \ 295 | > **ACTIVE** = `3` \ 296 | > Is active and in use. \ 297 | > **ATTACHED** = `4` \ 298 | > Is attached. 299 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/reference.md: -------------------------------------------------------------------------------- 1 | ## _Walter Modem Library / Micropython /_ API Reference 2 | 3 | - [Common](/walter-modem/micropython/reference/common.md) 4 | - [SIM & Network](/walter-modem/micropython/reference/sim_and_network.md) 5 | - [PDP Context Management](/walter-modem/micropython/reference/pdp_ctx_management.md) 6 | - [GNSS](/walter-modem/micropython/reference/gnss.md) 7 | - [Sockets](/walter-modem/micropython/reference/sockets.md) 8 | - [HTTP](/walter-modem/micropython/reference/http.md) 9 | - [MQTT](/walter-modem/micropython/reference/mqtt.md) 10 | - [Sleep](/walter-modem/micropython/reference/sleep.md) 11 | - [TLS & Certificates](/walter-modem/micropython/reference/tls_and_certificates.md) 12 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/sim_and_network.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [get_op_state](#get_op_state) 4 | - [set_op_state](#set_op_state) 5 | - [get_network_reg_state](#get_network_reg_state) 6 | - [get_rssi](#get_rssi) 7 | - [get_signal_quality](#get_signal_quality) 8 | - [get_cell_information](#get_cell_information) 9 | - [get_rat](#get_rat) 10 | - [set_rat](#set_rat) 11 | - [get_radio_bands](#get_radio_bands) 12 | - [get_sim_state](#get_sim_state) 13 | - [unlock_sim](#unlock_sim) 14 | - [set_network_selection_mode](#set_network_selection_mode) 15 | 16 | ## Enums Overview 17 | 18 | - [WalterModemNetworkRegState](#waltermodemnetworkregstate) 19 | - [WalterModemSQNMONIReportsType](#waltermodemsqnmonireportstype) 20 | - [WalterModemRat](#waltermodemrat) 21 | - [WalterModemNetworkSelMode](#waltermodemnetworkselmode) 22 | - [WalterModemOperatorFormat](#waltermodemoperatorformat) 23 | 24 | --- 25 | 26 | ## Methods 27 | 28 | ### `get_op_state` 29 | 30 | Retrieves the modem's current operational state. 31 | 32 | #### Example 33 | 34 | ```py 35 | modem_rsp = ModemRsp() 36 | 37 | if await modem.get_op_state(rsp=modem_rsp): 38 | print(WalterModemOpState.get_value_name(modem_rsp.op_state)) 39 | else: 40 | print('Failed to get modem op state') 41 | 42 | ``` 43 | 44 | #### Params 45 | 46 | | Param | Description | Default | 47 | | ----- | --------------------------------------- | -------- | 48 | | `rsp` | Reference to a modem response instance. | **None** | 49 | 50 | #### Returns 51 | 52 | `bool` 53 | True on success, False otherwise. 54 | 55 | --- 56 | 57 | ### `set_op_state` 58 | 59 | Sets the operational state of the modem. 60 | 61 | #### Example 62 | 63 | ```py 64 | if not await modem.set_op_state(op_state=WalterModemOpState.FULL): 65 | print('Failed to set modem op state') 66 | ``` 67 | 68 | #### Params 69 | 70 | | Param | Description | Default | 71 | | ---------- | -------------------------------------------------------------- | -------- | 72 | | `op_state` | The new [operational state](#waltermodemopstate) of the modem. | | 73 | | `rsp` | Reference to a modem response instance. | **None** | 74 | 75 | #### Returns 76 | 77 | `bool` 78 | True on success, False otherwise. 79 | 80 | --- 81 | 82 | ### `get_network_reg_state` 83 | 84 | Get the network registration state. 85 | This is buffered by the library and thus instantly available. 86 | 87 | #### Example 88 | 89 | ```py 90 | if modem.get_network_reg_state() in ( 91 | WalterModemNetworkRegState.REGISTERED_HOME, 92 | WalterModemNetworkRegState.REGISTERED_ROAMING 93 | ): 94 | # ... 95 | ``` 96 | 97 | #### Returns 98 | 99 | [`WalterModemNetworkRegState`](#waltermodemnetworkregstate) \ 100 | The current modem registration state 101 | 102 | --- 103 | 104 | ### `get_rssi` 105 | 106 | Retrieves the RSSI information. 107 | 108 | #### Example 109 | 110 | ```py 111 | modem_rsp = ModemRsp() 112 | 113 | if await modem.get_rssi(rsp=modem_rsp): 114 | print(modem_rsp.rssi) 115 | else: 116 | print('Failed to get modem RSSI') 117 | 118 | ``` 119 | 120 | #### Params 121 | 122 | | Param | Description | Default | 123 | | ----- | --------------------------------------- | -------- | 124 | | `rsp` | Reference to a modem response instance. | **None** | 125 | 126 | #### Returns 127 | 128 | `bool` 129 | True on success, False otherwise. 130 | 131 | --- 132 | 133 | ### `get_signal_quality` 134 | 135 | Retrieves information about the serving and neighbouring cells, 136 | including operator, cell ID, RSSI, and RSRP. 137 | 138 | #### Example 139 | 140 | ```py 141 | modem_rsp = ModemRsp() 142 | 143 | if await modem.get_signal_quality(rsp=modem_rsp): 144 | print(f'rsrp: {modem_rsp.signal_quality.rsrp}') 145 | print(f'rsrq: {modem_rsp.signal_quality.rsrq}') 146 | else: 147 | print('Failed to get signal quality') 148 | 149 | ``` 150 | 151 | #### Params 152 | 153 | | Param | Description | Default | 154 | | ----- | --------------------------------------- | -------- | 155 | | `rsp` | Reference to a modem response instance. | **None** | 156 | 157 | #### Returns 158 | 159 | `bool` 160 | True on success, False otherwise. 161 | 162 | --- 163 | 164 | ### `get_cell_information` 165 | 166 | Retrieves the modem's identity details, including IMEI, IMEISV, and SVN. 167 | 168 | #### Example 169 | 170 | ```py 171 | modem_rsp = ModemRsp() 172 | 173 | if await modem.get_cell_information(rsp=modem_rsp): 174 | print(f'net name: {modem_rsp.cell_information.net_name}') 175 | print(f'cid: {modem_rsp.cell_information.cid}') 176 | print(f'band: {modem_rsp.cell_information.band}') 177 | # ... 178 | else: 179 | print('Failed to get cell information') 180 | ``` 181 | 182 | #### Params 183 | 184 | | Param | Description | Default | 185 | | -------------- | -------------------------------------------------------------------------- | ---------------------------------------------- | 186 | | `reports_type` | The [type of cell information](#waltermodemsqnmonireportstype) to retreive | **WalterModemSQNMONIReportsType.SERVING_CELL** | 187 | | `rsp` | Reference to a modem response instance. | **None** | 188 | 189 | #### Returns 190 | 191 | `bool` 192 | True on success, False otherwise. 193 | 194 | --- 195 | 196 | ### `get_rat` 197 | 198 | Retrieves the Radio Access Technology (RAT) for the modem. 199 | 200 | #### Example 201 | 202 | ```py 203 | modem_rsp = ModemRsp() 204 | 205 | if await modem.get_rat(rsp=modem_rsp): 206 | print(modem_rsp.rat) 207 | else: 208 | print('Failed to get modem RAT') 209 | ``` 210 | 211 | #### Params 212 | 213 | | Param | Description | Default | 214 | | ----- | --------------------------------------- | -------- | 215 | | `rsp` | Reference to a modem response instance. | **None** | 216 | 217 | #### Returns 218 | 219 | `bool` 220 | True on success, False otherwise. 221 | 222 | --- 223 | 224 | ### `set_rat` 225 | 226 | Sets the Radio Access Technology (RAT) for the modem. 227 | 228 | #### Example 229 | 230 | ```py 231 | if not await modem.set_rat(WalterModemRat.LTEM): 232 | print('Failed to set RAT to LTEM') 233 | ``` 234 | 235 | #### Params 236 | 237 | | Param | Description | Default | 238 | | ----- | --------------------------------------- | -------- | 239 | | `rat` | The new [RAT](#waltermodemrat) | | 240 | | `rsp` | Reference to a modem response instance. | **None** | 241 | 242 | #### Returns 243 | 244 | `bool` 245 | True on success, False otherwise. 246 | 247 | --- 248 | 249 | ### `get_radio_bands` 250 | 251 | Retrieves the radio bands the modem is configured to use for network connection. 252 | 253 | #### Example 254 | 255 | ```py 256 | modem_rsp = ModemRsp() 257 | 258 | if await modem.get_radio_bands(rsp=modem_rsp): 259 | for band_sel in modem_rsp.band_sel_cfg_list: 260 | print(f'net_operator: {band_sel.net_operator} (rat: {band_sel.rat})') 261 | 262 | print('bands:') 263 | for band in band_sel: 264 | print(f' {band}') 265 | # ... 266 | else: 267 | print('Failed to get radio bands') 268 | ``` 269 | 270 | #### Params 271 | 272 | | Param | Description | Default | 273 | | ----- | --------------------------------------- | -------- | 274 | | `rsp` | Reference to a modem response instance. | **None** | 275 | 276 | #### Returns 277 | 278 | `bool` 279 | True on success, False otherwise. 280 | 281 | --- 282 | 283 | ### `get_sim_state` 284 | 285 | Retrieves the state of the SIM card. 286 | 287 | #### Example 288 | 289 | ```py 290 | modem_rsp = ModemRsp() 291 | 292 | if await modem.get_sim_state(rsp=modem_rsp): 293 | print(WalterModemSimState.get_value_name(modem_rsp.sim_state)) 294 | else: 295 | print('Failed to get SIM state') 296 | ``` 297 | 298 | #### Params 299 | 300 | | Param | Description | Default | 301 | | ----- | --------------------------------------- | -------- | 302 | | `rsp` | Reference to a modem response instance. | **None** | 303 | 304 | #### Returns 305 | 306 | `bool` 307 | True on success, False otherwise. 308 | 309 | --- 310 | 311 | ### `unlock_sim` 312 | 313 | Sets the SIM card's PIN code. 314 | 315 | > [!NOTE] 316 | > The modem must be in FULL or NO_RF operational state. 317 | 318 | #### Example 319 | 320 | ```py 321 | if not await modem.unlock_sim(): 322 | print('Failed to unlock SIM') 323 | ``` 324 | 325 | #### Params 326 | 327 | | Param | Description | Default | 328 | | ----- | ------------------------------------------------ | -------- | 329 | | `pin` | The PIN code of the SIM card or NULL for no pin. | **None** | 330 | | `rsp` | Reference to a modem response instance. | **None** | 331 | 332 | #### Returns 333 | 334 | `bool` 335 | True on success, False otherwise. 336 | 337 | --- 338 | 339 | ### `set_network_selection_mode` 340 | 341 | Sets the network selection mode for Walter. 342 | 343 | > [!NOTE] 344 | > This command is only available when the modem is in the fully operational state. 345 | 346 | #### Example 347 | 348 | ```py 349 | if not await modem.set_network_selection_mode(WalterModemNetworkSelMode.AUTOMATIC): 350 | print('Failed to set network selection mode to automatic') 351 | ``` 352 | 353 | #### Params 354 | 355 | | Param | Description | Default | 356 | | ----------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------- | 357 | | `mode` | The [network selection mode](#setnetworkselectionmode). | **WalterModemNetworkSelMode.AUTOMATIC** | 358 | | `operator_name` | The network operator name in case manual selection has been chosen. | **""** | 359 | | `operator_format` | The [format](#waltermodemoperatorformat) in which the network operator name is passed. | **WalterModemOperatorFormat.LONG_ALPHANUMERIC** | 360 | | `rsp` | Reference to a modem response instance. | **None** | 361 | 362 | #### Returns 363 | 364 | `bool` 365 | True on success, False otherwise. 366 | 367 | --- 368 | 369 | ## Enums 370 | 371 | ### `WalterModemNetworkRegState` 372 | 373 | Modem network registration states. 374 | 375 | > **NOT_SEARCHING** = `0` \ 376 | > **REGISTERED_HOME** = `1` \ 377 | > **SEARCHING** = `2` \ 378 | > **DENIED** = `3` \ 379 | > **UNKNOWN** = `4` \ 380 | > **REGISTERED_ROAMING** = `5` \ 381 | > **REGISTERED_SMS_ONLY_HOME** = `6` \ 382 | > **REGISTERED_SMS_ONLY_ROAMING** = `7` \ 383 | > **ATTACHED_EMERGENCY_ONLY** = `8` \ 384 | > **REGISTERED_CSFB_NOT_PREFERRED_HOME** = `9` \ 385 | > **REGISTERED_CSFB_NOT_PREFERRED_ROAMING** = `10` \ 386 | > **REGISTERED_TEMP_CONN_LOSS** = `80` \ 387 | 388 | ### `WalterModemSQNMONIReportsType` 389 | 390 | SQNMONI cell information reporting scopes. 391 | 392 | > **SERVING_CELL** = `0` \ 393 | > Reports only the serving cell. \ 394 | > **INTRA_FREQUENCY_CELLS** = `1` \ 395 | > Reports cells on the same frequency. \ 396 | > **INTER_FREQUENCY_CELLS** = `2` \ 397 | > Reports cells on different frequencies. \ 398 | > **ALL_CELLS** = `7` \ 399 | > Reports all available cells. \ 400 | > **SERVING_CELL_WITH_CINR** = `9` \ 401 | > Reports the serving cell with CINR (Carrier-to-Interference-plus-Noise Ratio). 402 | 403 | ### `WalterModemRat` 404 | 405 | Types of 3GPP access technologies supported by Walter. 406 | 407 | > **LTEM** = `1` \ 408 | > LTE-M (Long-Term Evolution for Machines). \ 409 | > **NBIOT** = `2` \ 410 | > NB-IoT (Narrowband Internet of Things). \ 411 | 412 | ### `WalterModemNetworkSelMode` 413 | 414 | Support network selection modes. 415 | 416 | > **AUTOMATIC** = `0` \ 417 | > Automatically selects a network. \ 418 | > **MANUAL** = `1` \ 419 | > Manually selects a network. \ 420 | > **UNREGISTER** = `2` \ 421 | > Disconnects from the network. \ 422 | > **MANUAL_AUTO_FALLBACK** = `4` \ 423 | > Manual selection with automatic fallback. 424 | 425 | ### `WalterModemOperatorFormat` 426 | 427 | Supported netowrk operator formats. 428 | 429 | > **LONG_ALPHANUMERIC** = `0` \ 430 | > Full operator name (e.g., "Vodafone UK"). \ 431 | > **SHORT_ALPHANUMERIC** = `1` \ 432 | > Short operator name (e.g., "Vodafone"). \ 433 | > **NUMERIC** = `2` \ 434 | > Numeric operator code (e.g., "23415"). 435 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/sleep.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [sleep](#sleep) 4 | - [config_PSM](#config_psm) 5 | - [config_EDRX](#config_edrx) 6 | 7 | ## Enums Overview 8 | 9 | - [WalterModemPSMMode](#waltermodempsmmode) 10 | - [WalterModemEDRXMODE](#waltermodemedrxmode) 11 | 12 | --- 13 | 14 | ## Methods 15 | 16 | ### `sleep` 17 | 18 | This function will put Walter into deep sleep or light sleep for a given duration. 19 | 20 | The typical power consumption is: 21 | - **1mA** in light sleep 22 | - **8µA** in deep sleep 23 | 24 | > [!NOTE] 25 | > Sleep applies to the ESP32-S3 only, the modem can remain active during sleep.\ 26 | > To reach the low power consumption described above, 27 | > it is recommended to configure the power saving functions of the modem. 28 | 29 | #### Example 30 | 31 | ```py 32 | modem.sleep(sleep_time_ms=20000, persist_mqtt_subs=False) 33 | ``` 34 | 35 | #### Params 36 | 37 | | Param | Description | Default | 38 | | ------------------- | ----------------------------------------------------------------- | --------- | 39 | | `sleep_time_ms` | The time to sleep *(in ms)* | | 40 | | `light_sleep` | True to go to lightsleep, False to go to deepsleep. | **False** | 41 | | `persist_mqtt_subs` | Whether or not to persist the mqtt subscriptions after deepsleep. | **False** | 42 | 43 | --- 44 | 45 | ### `config_PSM` 46 | 47 | Configure PSM on the modem. 48 | 49 | > [!NOTE] 50 | > What you get from the network may not be exactly the same as what was requested. 51 | 52 | #### Example 53 | 54 | ```py 55 | await modem.config_PSM( 56 | mode=WalterModemPSMMode.ENABLE_PSM, 57 | periodic_TAU_s=678 58 | ) 59 | ``` 60 | 61 | #### Params 62 | 63 | | Param | Description | Default | 64 | | ---------------- | ------------------------------------------------------------------------------- | -------- | 65 | | `mode` | Enable, Disable or Disable & Reset. ([WalterModemPSMMode](#waltermodempsmmode)) | | 66 | | `periodic_TAU_s` | The Periodic TAU in seconds. | **None** | 67 | | `active_time` | The Active Time in seconds. | **None** | 68 | | `rsp` | Reference to a modem response instance. | **None** | 69 | 70 | #### Returns 71 | 72 | `bool` 73 | True on success, False otherwise 74 | 75 | --- 76 | 77 | ### `config_EDRX` 78 | 79 | Configure eDRX on the modem. 80 | 81 | > [!NOTE] 82 | > What you get from the network may not be exactly the same as what was requested. 83 | 84 | #### Example 85 | 86 | ```py 87 | await modem.config_EDRX( 88 | mode=WalterModemEDRXMODE.ENABLE_EDRX, 89 | req_edrx_val='0101', 90 | req_ptw='0001' 91 | ) 92 | ``` 93 | 94 | #### Params 95 | 96 | | Param | Description | Default | 97 | | -------------- | --------------------------------------------------------------------------------- | -------- | 98 | | `mode` | Enable, Disable or Disable & Reset. ([WalterModemEDRXMODE](#waltermodemedrxmode)) | | 99 | | `req_edrx_val` | String: a nibble | **None** | 100 | | `req_ptw` | String: a nibble | **None** | 101 | | `rsp` | Reference to a modem response instance. | **None** | 102 | 103 | #### Returns 104 | 105 | `bool` 106 | True on success, False otherwise 107 | 108 | --- 109 | 110 | ## Enums 111 | 112 | ### `WalterModemPSMMode` 113 | 114 | Indication to disable or enable the use of PSM. 115 | 116 | > **DISABLE_PSM** = `0` \ 117 | > **ENABLE_PSM** = `1` \ 118 | > **DISABLE_AND_DISCARD_ALL_PARAMS** = `2`\ 119 | > Sets manufacturer specific defaults if available. 120 | 121 | ### `WalterModemEDRXMODE` 122 | 123 | Indication to disable or enable the use of eDRX. 124 | 125 | > **DISABLE_EDRX** = `0` \ 126 | > **ENABLE_EDRX** = `1` \ 127 | > **ENABLE_EDRX_AND_UNSOLICITED_RESULT_CODE** = `2` \ 128 | > **DISABLE_AND_DISCARD_ALL_PARAMS** = `3`\ 129 | > Sets manufacturer specific defaults if available. 130 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/sockets.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [create_socket](#create_socket) 4 | - [connect_socket](#connect_socket) 5 | - [socket_send](#socket_send) 6 | - [close_socket](#close_socket) 7 | 8 | ## Enums Overview 9 | 10 | - [WalterModemSocketProto](#waltermodemsocketproto) 11 | - [WalterModemSocketAcceptAnyRemote](#waltermodemsocketacceptanyremote) 12 | 13 | --- 14 | 15 | ## Methods 16 | 17 | ### `create_socket` 18 | 19 | Creates a new socket in a specified PDP context 20 | 21 | > [!NOTE] 22 | > Id's range from **1-6**. 23 | 24 | #### Example 25 | 26 | ```py 27 | modem_rsp = ModemRsp() 28 | socket_id: int 29 | 30 | if await modem.create_socket(rsp=modem_rsp): 31 | print('socket created successfully') 32 | socket_id = modem_rsp.socket_id 33 | ``` 34 | 35 | #### Params 36 | 37 | | Param | Description | Default | 38 | | ------------------ | ----------------------------------------------------------------------- | -------- | 39 | | `pdp_context_id` | The PDP context id. | **1** | 40 | | `mtu` | The maximum transmission unit used by the socket. | **300** | 41 | | `exchange_timeout` | The maximum number of seconds this socket can be inactive. | **90** | 42 | | `conn_timeout` | The maximum number of seconds this socket is allowed to try to connect. | **60** | 43 | | `send_delay_ms` | The number of milliseconds send delay. | **5000** | 44 | | `rsp` | Reference to a modem response instance. | **None** | 45 | 46 | #### Returns 47 | 48 | `bool` 49 | True on success, False otherwise. 50 | 51 | --- 52 | 53 | ### `connect_socket` 54 | 55 | Connects a socket to a remote host, 56 | allowing data exchange once the connection is successful. 57 | 58 | #### Example 59 | 60 | ```py 61 | SERV_ADDR = '64.255.64.140' 62 | """The address of the server to upload the data to""" 63 | 64 | SERV_PORT = 1999 65 | """The port on which the server is listening""" 66 | 67 | if await modem.connect_socket( 68 | remote_host=SERV_ADDR, 69 | remote_port=SERV_PORT, 70 | local_port=SERV_PORT 71 | ): 72 | print(f'Connected to server {SERV_ADDR}:{SERV_PORT}') 73 | else: 74 | print('Could not connect socket') 75 | ``` 76 | 77 | #### Params 78 | 79 | | Param | Description | Default | 80 | | ------------------- | ---------------------------------------------------------------------- | --------------------------------------- | 81 | | `remote_host` | The remote IPv4/IPv6 or hostname to connect to. | | 82 | | `remote_port` | The remote port to connect on. | | 83 | | `local_port` | The local port in case of an UDP socket. | | 84 | | `socket_id` | The id of the socket to connect. | **1** | 85 | | `protocol` | The [protocol](#waltermodemsocketproto) to use, UDP by default. | **ModemSocketProto.UDP** | 86 | | `accept_any_remote` | How to [accept remote](#waltermodemsocketacceptanyremote) UDP packets. | **ModemSocketAcceptAnyRemote.DISABLED** | 87 | | `rsp` | Reference to a modem response instance. | **None** | 88 | 89 | #### Returns 90 | 91 | `bool` 92 | True on success, False otherwise. 93 | 94 | --- 95 | 96 | ### `socket_send` 97 | 98 | Send data over a socket. 99 | 100 | #### Example 101 | 102 | ```py 103 | async def loop(): 104 | global counter 105 | global socket_id 106 | data_buffer: bytearray = bytearray(network.WLAN().config('mac')) 107 | data_buffer.append(counter >> 8) 108 | data_buffer.append(counter & 0xff) 109 | 110 | print('Attempting to transmit data') 111 | if not await modem.socket_send(data=data_buffer, socket_id=socket_id): 112 | print('Failed to transmit data') 113 | return False 114 | 115 | print(f'Transmitted counter value: {counter}') 116 | counter += 1 117 | 118 | await asyncio.sleep(10) 119 | ``` 120 | 121 | #### params 122 | 123 | | Param | Description | Default | 124 | | ----------- | ----------------------------------- | -------------------- | 125 | | `data` | The data to send. | | 126 | | `socket_id` | The id of the socket to send over. | **1** | 127 | | `rai` | The release assistance information. | **ModemRai.NO_INFO** | 128 | | `rsp` | Reference to a modem instance. | **None** | 129 | 130 | #### Returns 131 | 132 | `bool` 133 | True on success, False otherwise. 134 | 135 | --- 136 | 137 | ### `close_socket` 138 | 139 | Close a socket connection. 140 | 141 | > [!WARNING] 142 | > Sockets can only be **closed** when they are **suspended or inactive**. 143 | 144 | #### Example 145 | 146 | ```py 147 | if await modem.close_socket(): 148 | print('Successfully closed the socket') 149 | else: 150 | print('Could not close the socket') 151 | ``` 152 | 153 | #### Params 154 | 155 | | Param | Description | Default | 156 | | ----------- | ------------------------------ | -------- | 157 | | `socket_id` | The id of the socket to close. | **1** | 158 | | `rsp` | Reference to a modem instance. | **None** | 159 | 160 | #### Returns 161 | 162 | `bool` 163 | True on success, False otherwise. 164 | 165 | --- 166 | 167 | ## Enums 168 | 169 | ### `WalterModemSocketProto` 170 | 171 | The protocol that us used by the socket. 172 | 173 | > **TCP** = `0` \ 174 | > Use the TCP protocol for the socket \ 175 | > **UDP** = `1` \ 176 | > Use the UDP protocol for the socket 177 | 178 | ### `WalterModemSocketAcceptAnyRemote` 179 | 180 | Possible methodologies on how a socket handles data from other hosts 181 | besides the IP-address and remote port it is configured for. 182 | 183 | > **DISABLED** = `0`\ 184 | > Do not accepty any remote data \ 185 | > **REMOTE_RX_ONLY** = `1`\ 186 | > Only acccept read \ 187 | > **REMOTE_RX_AND_TX** = `2` \ 188 | > Accept read write from remote 189 | -------------------------------------------------------------------------------- /walter-modem/micropython/reference/tls_and_certificates.md: -------------------------------------------------------------------------------- 1 | ## Methods Overview 2 | 3 | - [tls_config_profile](#tlsconfigprofile) 4 | - [tls_write_credential](#tls_write_credential) 5 | 6 | ## Enums Overview 7 | 8 | - [WalterModemTlsVersion](#waltermodemtlsversion) 9 | - [WalterModemTlsValidation](#waltermodemtlsvalidation) 10 | 11 | --- 12 | 13 | ## Methods 14 | 15 | ### `tls_config_profile` 16 | 17 | Configures TLS profiles in the modem, 18 | including optional client authentication certificates, 19 | validation levels, and TLS version. 20 | 21 | > [!NOTE] 22 | > This should be done in an initialiser sketch, 23 | > allowing later HTTP, MQTT, CoAP, or socket sessions to use the 24 | > preconfigured profile IDs 25 | 26 | #### Example 27 | 28 | ```py 29 | if not await modem.tls_config_profile( 30 | profile_id=1, 31 | tls_validation=WalterModemTlsValidation.NONE, 32 | tls_version=WalterModemTlsVersion.TLS_VERSION_13 33 | ): 34 | print('Failed to configure TLS profile') 35 | ``` 36 | 37 | #### Params 38 | 39 | | Param | Description | Default | 40 | | ----------------------- | ------------------------------------------------------ | -------- | 41 | | `profile_id` | Security profile id (1-6) | | 42 | | `tls_version` | TLS version | | 43 | | `tls_validation` | TLS validation level: nothing, URL, CA+period or all | | 44 | | `ca_certificate_id` | CA certificate for certificate validation index (0-19) | **None** | 45 | | `client_certificate_id` | Client TLS certificate index (0-19) | **None** | 46 | | `client_private_key` | Client TLS private key index (0-19) | **None** | 47 | | `rsp` | Reference to a modem response instance. | **None** | 48 | 49 | #### Returns 50 | 51 | `bool` True on success, False otherwise. 52 | 53 | --- 54 | 55 | ### `tls_write_credential` 56 | 57 | Upload a key or certificate to the modem NVRAM. 58 | 59 | > [!NOTE] 60 | > It is recommended to save credentials in index 10-19 to avoid overwriting 61 | > preinstalled certificates and (if applicable) BlueCherry cloud platform credentials. 62 | 63 | ### Example 64 | 65 | ```py 66 | await modem.tls_write_credential( 67 | is_private_key=False, 68 | slot_idx=SLOT_IDX, 69 | credential=CERT 70 | ) 71 | ``` 72 | 73 | ### Params 74 | 75 | | Param | Description | Default | 76 | | ---------------- | -------------------------------------------------------- | ------- | 77 | | `is_private_key` | True if it's a private key, False if it's a certificate. | | 78 | | `slot_idx` | Slot index within the modem NVRAM keystore. | | 79 | | `credential` | NULL-terminated string containing the PEM key/cert data. | | 80 | | `rsp` | Reference to a modem response instance. | | 81 | 82 | ### Returns 83 | 84 | `bool` True on success, False otherwise 85 | 86 | --- 87 | 88 | ### `tls_provision_keys` 89 | 90 | > [!WARNING] 91 | > **DEPRECATED:** This method will be removed in the near future.\ 92 | 93 | It is still present for backwards compatibility. 94 | Use [`tls_write_credential`](#tls_write_credential) instead. 95 | 96 | --- 97 | 98 | ## Enums 99 | 100 | ### `WalterModemTlsVersion` 101 | 102 | The TLS version to use. 103 | 104 | > **TLS_VERSION_10** = `0` \ 105 | > TLS 1.0, outdated and insecure. \ 106 | > **TLS_VERSION_11** = `1` \ 107 | > TLS 1.1, deprecated version. \ 108 | > **TLS_VERSION_12** = `2` \ 109 | > TLS 1.2, widely used and secure. \ 110 | > **TLS_VERSION_13** = `3` \ 111 | > TLS 1.3, latest and most secure version. \ 112 | > **TLS_VERSION_RESET** = `255` \ 113 | > Resets to default TLS version. 114 | 115 | ### `WalterModemTlsValidation` 116 | 117 | The TLS validation policy. 118 | 119 | > **NONE** = `0` \ 120 | > No TLS validation. \ 121 | > **CA** = `1` \ 122 | > Validates using a Certificate Authority. \ 123 | > **URL** = `4` \ 124 | > Validates the server URL. \ 125 | > **URL_AND_CA** = `5` \ 126 | > Validates both the URL and CA certificate. 127 | -------------------------------------------------------------------------------- /walter-modem/micropython/setup.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | This guide will walk you through installing the WalterModem library 4 | for Micropython 5 | 6 | > [!TIP] 7 | > If you haven't set up your Micropython dev environment yet, go through the 8 | > [Micropython Toolchain Setup](/developer-toolchains/micropython.md) first. 9 | 10 | ## Guide 11 | 12 | There are multiple ways to install the WalterModem library for Micropython. 13 | 14 | 15 | 16 | ### **MIP (Recommended)** 17 | 18 | [MIP](https://docs.micropython.org/en/latest/reference/packages.html) 19 | is similar in concept to Python's `pip` tool. 20 | It allows you to install packages from 21 | [micropython-lib](https://docs.micropython.org/en/latest/reference/glossary.html#term-micropython-lib) 22 | and from third-party sites *(including Github & Gitlab)*. 23 | 24 | You can use `mpremote`, the officially-supported tool for interacting 25 | with a MicroPython device, to install the Modem Library MIP packagae to your device. 26 | 27 | Simply run: 28 | 29 | ```shell 30 | mpremote mip install github:QuickSpot/walter-micropython 31 | ``` 32 | 33 | If needed, you can specify the device as such: 34 | 35 | ```shell 36 | mpremote connect mip install github:QuickSpot/walter-micropython 37 | ``` 38 | 39 | > [!TIP] 40 | > \ may look like: /dev/ttyACM0 (on Linux) or eg. "COM3" (on Windows) 41 | 42 | ### **Util Script** 43 | 44 | The [Micropython WalterModem](https://github.com/QuickSpot/walter-micropython.git) 45 | repository contains a quick install utility script, 46 | it will copy all library files to the correct place on the board. 47 | 48 | The script can be found under `util/install_walter_modem/` and is available for 49 | Linux *(.sh)* and Windows *(.ps1)*. 50 | 51 | The purpose of this utility is for convenience during development 52 | of the modem library itself or should there be any issues with 53 | [MIP](https://docs.micropython.org/en/latest/reference/packages.html). 54 | 55 | > [!NOTE] 56 | > This utility script requires mpremote to run, if not installed already, 57 | > you can do so by running: `pip install mpremote` 58 | 59 | > [!TIP] 60 | > If the script doesn't run, make sure it is executable first, on linux: 61 | > `chmod +x ` 62 | 63 | ### **Manual Copy (mpremote)** 64 | 65 | You can use mpremote to manually copy the WalterModem libary to your device. 66 | 67 | 1. Clone the [Micropython WalterModem](https://github.com/QuickSpot/walter-micropython.git) 68 | 2. Change Directory into the repository 69 | 3. Make the lib directory on the MicroPython device: 70 | 71 | ```shell 72 | mpremote mkdir lib 73 | ``` 74 | 75 | 4. Copy the modem library to the lib folder 76 | on the MicroPython device, to install it. 77 | 78 | ```shell 79 | mpremote cp -r walter_modem :lib/ 80 | ``` 81 | 82 | If needed you can specify the device as such: 83 | 84 | ```shell 85 | mpremote connect cp -r walter_modem :lib/ 86 | ``` 87 | 88 | > [!TIP] 89 | > \ may look like: /dev/ttyACM0 (on Linux) or eg. "COM3" (on Windows) 90 | 91 | ### **Manual Copy (Thonny)** 92 | 93 | #### 1. Clone the Walter MicroPython library 94 | 95 | ```shell 96 | git clone https://github.com/QuickSpot/walter-micropython.git 97 | ``` 98 | 99 | #### 2. Open the repository in Thonny 100 | 101 | - Open Thonny and ensure that the MicroPython interpreter is set up correctly 102 | (See the [Micropython Toolchain Setup; step 6](/developer-toolchains/micropython.md#6-uploading-scripts-via-thonny)). 103 | - Go to `File` -> `Open...`. 104 | - Navigate to the local directory where you cloned the repository. 105 | 106 | #### 3. Upload all files to Walter 107 | 108 | On the Micropython device, create a new directory called `lib`. 109 | 110 | ![thonney-new-dir](img/thonny-new-dir.png) 111 | 112 | Double click on the newly created `lib` directory to open it. 113 | 114 | ![thonny-lib-open](img/thonny-lib-open.png) 115 | 116 | In the cloned repository, right click on the directory `walter_modem` 117 | and select `Upload to /lib` 118 | 119 | ![thonny-upload-to-lib](img/thonny-upload-to-lib.png) 120 | 121 | 122 | 123 | Now, the library is uploaded to Walter. 124 | 125 | You can find some example applications for Walter in the `examples` folder. 126 | 127 | ## Library structure 128 | 129 | - `core.py`: The core functionality of the library. 130 | - `modem.py`: The actual modem class you end up importing. It ties everything 131 | together, inheriting the mixins. 132 | - `mixins`: A folder containing the protocol/purpose specifc methods to interact 133 | with the library, such as common, sleep, http, mqtt, sockets, ... 134 | - `enums.py`: Where all the enums used in the library are defined. 135 | - `structs.py`: Where all the "structs" used in the library are defined. 136 | - `util.py`: Internal library utility functions. 137 | - `queue.py`: A third-party `Queue` implementation 138 | that is missing in `uasyncio`, MicroPython's `asyncio` implementation. 139 | The code is cherry-picked [from this great repo by Peter Hinch](https://github.com/peterhinch/micropython-async). 140 | 141 | The library makes use of asyncio coroutines for communicating with the modem, 142 | queueing commands and ensuring nothing is blocking. 143 | 144 | ```python 145 | import asyncio 146 | 147 | from walter_modem import Modem 148 | 149 | from walter_modem.enums import ( 150 | # ... 151 | ) 152 | 153 | from walter_modem.structs import ( 154 | # ... 155 | ) 156 | 157 | modem = Modem() 158 | 159 | async def main(): 160 | # ... 161 | # ...... 162 | await modem.begin() 163 | # ...... 164 | # ... 165 | 166 | asyncio.run(main()) 167 | ``` 168 | -------------------------------------------------------------------------------- /walter-modem/walter-modem.md: -------------------------------------------------------------------------------- 1 | ## Walter Modem Library 2 | 3 | - [Arduino & ESP-IDF](/walter-modem/arduino_esp-idf/arduino_esp-idf.md) 4 | - [Setup](/walter-modem/arduino_esp-idf/setup/setup.md) 5 | - [Arduino](/walter-modem/arduino_esp-idf/setup/arduino.md) 6 | - [ESP-IDF](/walter-modem/arduino_esp-idf/setup/esp-idf.md) 7 | - [API Reference](/walter-modem/arduino_esp-idf/reference/reference.md) 8 | - [Sockets](/walter-modem/arduino_esp-idf/reference/sockets.md) 9 | - [HTTP](/walter-modem/arduino_esp-idf/reference/http.md) 10 | - [MQTT](/walter-modem/arduino_esp-idf/reference/mqtt.md) 11 | - [Micropython](/walter-modem/micropython/micropython.md) 12 | - [Setup](/walter-modem/micropython/setup.md) 13 | - [API Reference](/walter-modem/micropython/reference/reference.md) 14 | - [Common](/walter-modem/micropython/reference/common.md) 15 | - [SIM & Network](/walter-modem/micropython/reference/sim_and_network.md) 16 | - [PDP Context Management](/walter-modem/micropython/reference/pdp_ctx_management.md) 17 | - [GNSS](/walter-modem/micropython/reference/gnss.md) 18 | - [Sockets](/walter-modem/micropython/reference/sockets.md) 19 | - [HTTP](/walter-modem/micropython/reference/http.md) 20 | - [MQTT](/walter-modem/micropython/reference/mqtt.md) 21 | - [Sleep](/walter-modem/micropython/reference/sleep.md) 22 | - [TLS & Certificates](/walter-modem/micropython/reference/tls_and_certificates.md) 23 | --------------------------------------------------------------------------------