espressif/asio
uploaded 1 week ago

Cross-platform C++ library for network and I/O programming

readme

# ASIO port [![Component Registry](https://components.espressif.com/components/espressif/asio/badge.svg)](https://components.espressif.com/components/espressif/asio) Asio is a cross-platform C++ library, see https://think-async.com/Asio/. It provides a consistent asynchronous model using a modern C++ approach. ## Examples Get started with examples [examples](https://github.com/espressif/esp-protocols/tree/master/components/asio/examples) ## Documentation * View the full [html documentation](https://docs.espressif.com/projects/esp-protocols/asio/docs/latest/index.html)

changelog

# Changelog ## [1.28.2~0](https://github.com/espressif/esp-protocols/commits/asio-1.28.2_0) ### Bug Fixes - reference protocol_examples_common from IDF ([09abb18](https://github.com/espressif/esp-protocols/commit/09abb18)) - specify override_path in example manifest files ([1d8923c](https://github.com/espressif/esp-protocols/commit/1d8923c)) ### Updated - docs(asio): Updates asio docs ([ce9337d](https://github.com/espressif/esp-protocols/commit/ce9337d)) ## [1.28.0~0](https://github.com/espressif/esp-protocols/commits/asio-1.28.0~0) ### Features - Updates asio to 1.28 ([b310abe](https://github.com/espressif/esp-protocols/commit/b310abe)) ### Bug Fixes - Makes the examples to override path ([842b2b2](https://github.com/espressif/esp-protocols/commit/842b2b2)) - Removes esp_exception and make all examples to use exceptions ([c1c9350](https://github.com/espressif/esp-protocols/commit/c1c9350)) - removed Wno-format flag and fixed formatting warnings ([c48e442](https://github.com/espressif/esp-protocols/commit/c48e442)) - added idf_component.yml for examples ([d273e10](https://github.com/espressif/esp-protocols/commit/d273e10)) - Reintroduce missing CHANGELOGs ([200cbb3](https://github.com/espressif/esp-protocols/commit/200cbb3), [#235](https://github.com/espressif/esp-protocols/issues/235)) ### Updated - docs(common): updated component and example links ([f48d9b2](https://github.com/espressif/esp-protocols/commit/f48d9b2)) - docs(common): improving documentation ([ca3fce0](https://github.com/espressif/esp-protocols/commit/ca3fce0)) - Add homepage URL and License to all components ([ef3f0ee](https://github.com/espressif/esp-protocols/commit/ef3f0ee)) - Added badges with version of components to the respective README files ([e4c8a59](https://github.com/espressif/esp-protocols/commit/e4c8a59)) - CI: Fix ASIO example test ([6e2bb51](https://github.com/espressif/esp-protocols/commit/6e2bb51)) - Examples: using pytest.ini from top level directory ([aee016d](https://github.com/espressif/esp-protocols/commit/aee016d)) - CI: fixing the files to be complient with pre-commit hooks ([945bd17](https://github.com/espressif/esp-protocols/commit/945bd17)) ## [1.14.1~3](https://github.com/espressif/esp-protocols/commits/f148c98) ### Updated - ASIO: Updated package version to "1.14.1~3" ([f148c98](https://github.com/espressif/esp-protocols/commit/f148c98)) - ASIO: Example tests integration ([5193ebc](https://github.com/espressif/esp-protocols/commit/5193ebc)) ## [1.0.2](https://github.com/espressif/esp-protocols/commits/57afa38) ### Updated - Bump asio/mdns/esp_websocket_client versions ([57afa38](https://github.com/espressif/esp-protocols/commit/57afa38)) - ignore format warnings ([d66f9dc](https://github.com/espressif/esp-protocols/commit/d66f9dc)) - asio: Fix exampels build ([3662c14](https://github.com/espressif/esp-protocols/commit/3662c14)) ## [1.0.1](https://github.com/espressif/esp-protocols/commits/055f051) ### Updated - ASIO: Initial version based on IDF 5.0 with history ([055f051](https://github.com/espressif/esp-protocols/commit/055f051)) - asio: Disable concepts support Fix example for compatibility with C++20 ([ac7bf46](https://github.com/espressif/esp-protocols/commit/ac7bf46), [IDF@9dba047](https://github.com/espressif/esp-idf/commit/9dba0476a01cd80d76e21706ad350009606b877e)) - lwip: Update socket API to include port-version of sockets/netdb ([057a5d2](https://github.com/espressif/esp-protocols/commit/057a5d2), [IDF@53c009e](https://github.com/espressif/esp-idf/commit/53c009e62631bae569fa849c6b6c9e70a10b3afe)) - esp_netif/lwip: Implement basic support for vanilla-lwip (2.1.3-REL) ([63bff63](https://github.com/espressif/esp-protocols/commit/63bff63), [IDF@5b471a1](https://github.com/espressif/esp-idf/commit/5b471a18489b056f65fe8dcbb2c992d27909ebc9)) - mbedtls: Remove certs.c and certs.h from port directory ([e3c4391](https://github.com/espressif/esp-protocols/commit/e3c4391), [IDF@f31d8dd](https://github.com/espressif/esp-idf/commit/f31d8dd2955be0fe949340dcf3b043ec6daf4378)) - mbedtls-3 update: 1) Fix build issue in mbedtls 2) skip the public headers check in IDF 3)Update Kconfig Macros 4)Remove deprecated config options 5) Update the sha API according to new nomenclature 6) Update mbedtls_rsa_init usage 7) Include mbedtls/build_info.h instead of mbedtls/config.h 8) Dont include check_config.h 9) Add additional error message in esp_blufi_api.h ([9813818](https://github.com/espressif/esp-protocols/commit/9813818), [IDF@4512253](https://github.com/espressif/esp-idf/commit/45122533e0bca5d538585e22308f14b74c33e474)) - asio: Use internal ssl context and engine impl ([f605fdd](https://github.com/espressif/esp-protocols/commit/f605fdd), [IDF@d823106](https://github.com/espressif/esp-idf/commit/d823106aa6b24b8bdcc30373513c8688c61438c4)) - Build & config: Remove leftover files from the unsupported "make" build system ([abbc8d9](https://github.com/espressif/esp-protocols/commit/abbc8d9), [IDF@766aa57](https://github.com/espressif/esp-idf/commit/766aa5708443099f3f033b739cda0e1de101cca6)) - openssl: Add deprecation warning to ssl.h ([a029774](https://github.com/espressif/esp-protocols/commit/a029774), [IDF@cfc0018](https://github.com/espressif/esp-idf/commit/cfc001870c5e0afed7b42b6bf8c326eae053fe96)) - asio coap: If LWIP IPV6 is disabled, automatically don't build asio & coap ([cc0f2b3](https://github.com/espressif/esp-protocols/commit/cc0f2b3), [IDF@e305f29](https://github.com/espressif/esp-idf/commit/e305f2938278c2a39e75c21a3ed59d8f4d4e62fa)) - asio: update copyright notice ([47d57a5](https://github.com/espressif/esp-protocols/commit/47d57a5), [IDF@2d0895e](https://github.com/espressif/esp-idf/commit/2d0895e9a98bc7846d0ac7321f2b86b47346bf21)) - Whitespace: Automated whitespace fixes (large commit) ([622a360](https://github.com/espressif/esp-protocols/commit/622a360), [IDF@66fb5a2](https://github.com/espressif/esp-idf/commit/66fb5a29bbdc2482d67c52e6f66b303378c9b789)) - cmake: Apply cmakelint fixes ([4358c3c](https://github.com/espressif/esp-protocols/commit/4358c3c), [IDF@e82eac4](https://github.com/espressif/esp-idf/commit/e82eac4354b8b4111697656f3acce7450eeff366)) - asio: option to use wolfSSL as TLS stack for ASIO ([c05558b](https://github.com/espressif/esp-protocols/commit/c05558b), [IDF@1c8171c](https://github.com/espressif/esp-idf/commit/1c8171c3e8d5a67e47dc8d6abac27ad2989470c3)) - asio: Basic SSL/TLS support in asio port for ESP platform ([dab1230](https://github.com/espressif/esp-protocols/commit/dab1230), [IDF@9459c0d](https://github.com/espressif/esp-idf/commit/9459c0dd432fdd0fccb49ea65bb5c72d1849e1ba)) - asio: updated ASIO port to use latest asio and esp-idf features ([9190917](https://github.com/espressif/esp-protocols/commit/9190917), [IDF@13d603e](https://github.com/espressif/esp-idf/commit/13d603e486624380d49f2e89614b10425c208d14)) - components: use new component registration api ([9e83b1e](https://github.com/espressif/esp-protocols/commit/9e83b1e), [IDF@9eccd7c](https://github.com/espressif/esp-idf/commit/9eccd7c0826d6cc2e9de59304d1e5f76c0063ccf)) - Rename Kconfig options (root) ([3b49d1f](https://github.com/espressif/esp-protocols/commit/3b49d1f), [IDF@c5000c8](https://github.com/espressif/esp-idf/commit/c5000c83d250896fffbddd7a3991384ea0fc286d)) - cmake: make main a component again ([57672d5](https://github.com/espressif/esp-protocols/commit/57672d5), [IDF@d9939ce](https://github.com/espressif/esp-idf/commit/d9939cedd9b44d63dc148354c3a0a139b9c7113d)) - asio: initial idf port of asio library without ssl ([5472d5c](https://github.com/espressif/esp-protocols/commit/5472d5c), [IDF@1ef13c5](https://github.com/espressif/esp-idf/commit/1ef13c524c484e9fb62e6c0b11482c30c5383728))

readme of asio_chat example

| Supported Targets | ESP32 | ESP32-S2 | ESP32-S3 | ESP32-C3 | | ----------------- | ----- | -------- | -------- | -------- | # Asio chat client and server examples (See the README.md file in the upper level 'examples' directory for more information about examples.) The application aims to demonstrate a simple use of Asio library in different modes. In project settings it could be configured to run either a Asio chat server, a Asio chat client, or both. ## How to use example The example is configured by default as an Asio chat client. Note that the example uses string representation of IP addresses and ports. You can find the upstream asio chat implementation [here] https://github.com/chriskohlhoff/asio/tree/master/asio/src/examples/cpp11/chat ### Asio Client In the client mode, the example connects to the configured address, sends the message, which was inserted as an input in the terminal, and receives a response. ### Asio Server In the server mode, Asio chat server with a specified port number is created and being polled till a connection request from the client arrives. Chat server echoes a message (received from any client) to all connected clients. ## Configure the project ``` idf.py menuconfig ``` Set following parameters under Example Configuration Options: * Set `EXAMPLE_CHAT_SERVER` to use the example as an ASIO chat server * Configure `EXAMPLE_CHAT_SERVER_BIND_PORT` to the port number. * Set `EXAMPLE_CHAT_CLIENT` to use the example as an ASIO chat client * Configure `EXAMPLE_CHAT_CLIENT_CONNECT_ADDRESS` to a string representation of the address to connect the client to. * Configure `EXAMPLE_CHAT_CLIENT_CONNECT_PORT` to the port number. * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more d etails. ## Running the example in server mode - Configure the example according "Configure the project" section. - Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - Connect to the server using multiple clients, for example using any option below. - build and run asio chat client on your host machine - run chat_client asio example on ESP platform - since chat messages consists of ASCII size and message, it is possible to netcat `nc IP PORT` and type for example ` 4ABC<CR>` to transmit 'ABC\n' ## Running the example in client mode - Configure the example according "Configure the project" section. - Start chat server either on host machine or as another ESP device running chat_server example. - Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet. - Receive and send messages to/from other clients on stdin/stdout via serial terminal. See the README.md file in the upper level 'examples' directory for more information about examples.

readme of async_request example

| Supported Targets | ESP32 | | ----------------- | ----- | # Async request using ASIO (See the README.md file in the upper level 'examples' directory for more information about examples.) The application aims to show how to compose async operations using ASIO to build network protocols and operations. # Configure and Building example This example doesn't require any configuration, just build it with ``` idf.py build ``` # Async operations composition and automatic lifetime control On this example we compose the operation by starting the next step in the chain inside the completion handler of the previous operation. Also we pass the `Connection` class itself as the parameter of its final handler to be owned by the following operation. This is possible due to the control of lifetime by the usage of `std::shared_ptr`. The control of lifetime of the class, done by `std::shared_ptr` usage, guarantee that the data will be available for async operations until it's not needed any more. This makes necessary that all of the async operation class must start its lifetime as a `std::shared_ptr` due to the usage of `std::enable_shared_from_this`. ``` User creates a shared_ptr──┐ of AddressResolution and │ ask for resolve. │ The handler for the ┌▼─────────────────────┐ complete operation is sent│ AddressResolution │ In the completion of resolve a connection is created. └─────────────────┬────┘ AddressResolution is automaticly destroyed since it's │ no longer needed ┌─▼────────────────────────────────────┐ │ Connection │ └──────┬───────────────────────────────┘ Http::Session is created once we have a Connection. │ Connection is passed to Http::Session that holds it │ avoiding it's destruction. │ ┌─▼───────────────────────────────┐ │ Http::Session │ └────────┬────────────────────────┘ After the HTTP request is │ sent the completion handler │ is called. │ └────►Completion Handler() ``` The previous diagram shows the process and the life span of each of the tasks in this examples. At each stage the object responsible for the last action inject itself to the completion handler of the next stage for reuse.

readme of socks4 example

| Supported Targets | ESP32 | ESP32-S2 | | ----------------- | ----- | ----- | # Async request using ASIO (See the README.md file in the upper level 'examples' directory for more information about examples.) The application aims to show how to connect to a Socks4 proxy using async operations with ASIO. The SOCKS protocol is briefly described by the diagram below. ┌──────┐ ┌─────┐ ┌──────┐ │Client│ │Proxy│ │Target│ └──┬───┘ └──┬──┘ └──┬───┘ │ │ │ │ ╔═╧══════════════╗ │ ══════════════════════╪════════════════════════╣ Initialization ╠═══╪════════════════════════════════════════════ │ ╚═╤══════════════╝ │ │ │ │ ╔══════════════════╗│ │ │ ║We establish a ░║│ Socket Connection │ │ ║TCP connection ║│ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ > │ ║and get a socket ║│ │ │ ╚══════════════════╝│ │ │ │ │ │ │ ╔═╧══════════════╗ │ ══════════════════════╪════════════════════════╣ Socks Protocol ╠═══╪════════════════════════════════════════════ │ ╚═╤══════════════╝ │ │ │ │ │ Client Connection Request│ │ │ ─────────────────────────> │ │ │ │ │ │ │ │ ╔════════════╪═══════╤══════════╪════════════════════════════════╗ │ ║ TARGET CONNECTION │ │ ║ │ ╟────────────────────┘ │ ╔═══════════════════╗ ║ │ ║ │ Socket Connection│ ║Proxy establishes ░║ ║ │ ║ │ <─ ─ ─ ─ ─ ─ ─ ─ > ║ TCPconnection ║ ║ │ ║ │ │ ║ with target host ║ ║ │ ╚════════════╪══════════════════╪══╚═══════════════════╝═════════╝ │ │ │ │ Response packet │ │ │ <───────────────────────── │ │ │ │ │ │ │ │ │ ╔═══════╗ │ ══════════════════════╪══════════════════════════╪══╣ Usage ╠═══════╪════════════════════════════════════════════ │ │ ╚═══════╝ │ │ │ │ ╔═════════════════╗│ │ │ ║Client uses the ░║│ │ │ ║ socket opened ║│ │ │ ║ with proxy ║│ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> ║to communicate ║│ │ │ ║ ║│ │ │ ╚═════════════════╝┴───┐ ┌──┴──┐ ┌──┴───┐ │Client│ │Proxy│ │Target│ └──────┘ └─────┘ └──────┘ # Configure and Building example This example requires the proxy address to be configured. You can do this using the menuconfig option. Proxy address and port must be configured in order for this example to work. If using Linux ssh can be used as a proxy for testing. ``` ssh -N -v -D 0.0.0.0:1080 localhost ``` # Async operations composition and automatic lifetime control For documentation about the structure of this example look into [async\_request README](../async_request/README.md).

readme of ssl_client_server example

| Supported Targets | ESP32 | ESP32-S2 | ESP32-S3 | ESP32-C3 | | ----------------- | ----- | -------- | -------- | -------- | # Asio SSL client/server example Simple Asio client and server with SSL/TLS transport ## How to Use Example ### Hardware Required This example can be executed on any ESP platform board. No external connection is required, it is recommended though to connect to internet or a local network via WiFi or Ethernet to easily exercise features of this example. ### Configure the project * Open the project configuration menu (`idf.py menuconfig`) * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * Enable the ASIO client and set server's host name to examine client's functionality. The ASIO client connects to the configured server and sends default payload string "GET / HTTP/1.1" * Enable the ASIO server to examine server's functionality. The ASIO server listens to connection and echos back what was received. ### Build and Flash Build the project and flash it to the board, then run monitor tool to view serial output: ``` idf.py -p PORT flash monitor ``` (To exit the serial monitor, type ``Ctrl-]``.) See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects. ## Example Output ### Client connecting to public server The below output illustrates the client connecting to a public https server. ``` I (1267) example_connect: Waiting for IP(s) I (2587) wifi:new:<11,0>, old:<1,0>, ap:<255,255>, sta:<11,0>, prof:1 I (3367) wifi:state: init -> auth (b0) I (3377) wifi:state: auth -> assoc (0) I (3387) wifi:state: assoc -> run (10) I (3397) wifi:security type: 3, phy: bgn, rssi: -49 I (3397) wifi:pm start, type: 1 I (3457) wifi:AP's beacon interval = 102400 us, DTIM period = 1 I (4747) example_connect: Got IPv6 event: Interface "example_connect: sta" address: fe80:0000:0000:0000:260a:xxxx:xxxx:xxxx, type: ESP_IP6_ADDR_IS_LINK_LOCAL I (5247) esp_netif_handlers: example_connect: sta ip: 192.168.32.69, mask: 255.255.252.0, gw: 192.168.32.3 I (5247) example_connect: Got IPv4 event: Interface "example_connect: sta" address: 192.168.32.69 I (5257) example_connect: Connected to example_connect: sta I (5257) example_connect: - IPv4 address: 192.168.32.69 I (5267) example_connect: - IPv6 address: fe80:0000:0000:0000:260a:xxxx:xxxx:xxxx, type: ESP_IP6_ADDR_IS_LINK_LOCAL W (5277) esp32_asio_pthread: pthread_condattr_setclock: not yet supported! W (5297) esp32_asio_pthread: pthread_condattr_setclock: not yet supported! Reply: HTTP/1.1 200 OK D ``` ### Both server and client enabled The below output demonstrates the client connecting to the ASIO server via loopback interface, so no WiFi, nor Ethernet connection was established. ``` I (0) cpu_start: App cpu up. I (495) heap_init: Initializing. RAM available for dynamic allocation: I (502) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM I (508) heap_init: At 3FFB5400 len 0002AC00 (171 KiB): DRAM I (515) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM I (521) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM I (527) heap_init: At 4008BB80 len 00014480 (81 KiB): IRAM I (534) cpu_start: Pro cpu start user code I (556) spi_flash: detected chip: gd I (556) spi_flash: flash io: dio W (556) spi_flash: Detected size(4096k) larger than the size in the binary image header(2048k). Using the size in the binary image header. I (566) cpu_start: Starting scheduler on PRO CPU. I (0) cpu_start: Starting scheduler on APP CPU. I (600) example_connect: Waiting for IP(s) W (600) esp32_asio_pthread: pthread_condattr_setclock: not yet supported! W (1610) esp32_asio_pthread: pthread_condattr_setclock: not yet supported! W (1610) esp32_asio_pthread: pthread_condattr_setclock: not yet supported! Server received: GET / HTTP/1.1 Reply: GET / HTTP/1.1 ``` See the README.md file in the upper level 'examples' directory for more information about examples.

readme of tcp_echo_server example

| Supported Targets | ESP32 | ESP32-S2 | ESP32-S3 | ESP32-C3 | | ----------------- | ----- | -------- | -------- | -------- | # Asio TCP echo server example Simple Asio TCP echo server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. - Asio TCP server is started on port number defined through the project configuration. - Server receives and echoes back messages transmitted from client. ## Running the example - Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". - Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - You can now send a TCP message and check it is repeated, for example using netcat `nc IP PORT`. See the README.md file in the upper level 'examples' directory for more information about examples.

readme of udp_echo_server example

| Supported Targets | ESP32 | ESP32-S2 | ESP32-S3 | ESP32-C3 | | ----------------- | ----- | -------- | -------- | -------- | # Asio UDP echo server example Simple Asio UDP echo server using WiFi STA or Ethernet. ## Example workflow - Wi-Fi or Ethernet connection is established, and IP address is obtained. - Asio UDP server is started on port number defined through the project configuration - Server receives and echoes back messages transmitted from client ## Running the example - Open the project configuration menu (`idf.py menuconfig`) to configure Wi-Fi or Ethernet. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. - Set server port number in menuconfig, "Example configuration". - Run `idf.py -p PORT flash monitor` to build and upload the example to your board and connect to it's serial terminal. - Wait for the board to connect to WiFi or Ethernet (note the IP address). - You can now send a UDP message and check it is repeated, for example using netcat `nc -u IP PORT`. See the README.md file in the upper level 'examples' directory for more information about examples.

Links

Supports all targets

License: BSL-1.0

To add this component to your project, run:

idf.py add-dependency "espressif/asio^1.28.2"

or download archive

Dependencies

  • ESP-IDF >=5.0

    • Examples:

    asio_chat

    more details

    async_request

    more details

    socks4

    more details

    ssl_client_server

    more details

    tcp_echo_server

    more details

    udp_echo_server

    more details

    Stats

    • Downloaded in total
      Downloaded in total 2.0k times
    • Downloaded this version
      This version: 66 times

    Badge

    espressif/asio version: 1.28.2 |
    report abuse