Examples

This directory contains application examples of how to use u-connectClient. The examples make use of the example ports.

All examples are designed to work with both OS and no-OS configurations by using the shared utilities in example_utils.c/h. This demonstrates the portability of u-connectClient across different execution environments.

Files	Description
http_example.c	Example of doing a HTTP GET request using the uCx API. This example can be compiled for both OS (POSIX) and no-OS (bare-metal) configurations. This example will also illustrate how to switch baud rate for increased throughput.
fw_upgrade_example.c	Example of performing firmware upgrade using AT+USYFWUS command and XMODEM protocol. This example can be compiled for both OS (POSIX) and no-OS (bare-metal) configurations.
ble_scan_example.c	Example of performing a BLE device discovery scan. Demonstrates how to start/stop BLE scanning and handle scan result URCs.
ble_advertise_example.c	Example of BLE advertising with custom advertising data. Demonstrates how to configure and start BLE advertising.
wifi_scan_example.c	Example of scanning for nearby WiFi access points. Lists available networks with signal strength and security information.
wifi_ap_example.c	Example of starting a WiFi access point (AP mode). Demonstrates AP configuration and handling station connect/disconnect events via URCs.
socket_example.c	Example of raw TCP socket communication. Demonstrates socket creation, connection, data transfer, and URC-driven event handling.
example_utils.c/h	Common utility functions that work with both OS and no-OS configurations, providing AT client initialization, event handling, and sleep functionality.

Configuration

All configuration is done via config.local.h. Copy the template and edit it:

cp config.local.h.template config.local.h

Then edit the macros:

#define U_EXAMPLE_SSID "your-wifi-ssid"
#define U_EXAMPLE_WPA_PSK "your-wifi-password"
// Uncomment if you need a different UART:
// #define U_EXAMPLE_UART "/dev/ttyUSB1"

This file is .gitignored, so your credentials stay out of commits. All examples automatically include this file when it exists.

Building

The examples use PyInvoke for build automation. Install it with:

> pip install invoke

Available platforms

Build tasks are organized by platform namespace:

Namespace	Platform	Host requirement
`linux.*`	Linux (POSIX)	Linux host
`win32.*`	Windows	Windows host
`stm32.*`	STM32F4 (FreeRTOS)	ARM toolchain or `--docker` flag

Listing available tasks

To see all available build tasks, run from the examples/ directory:

> invoke --list
Available tasks:

  build-all                   Build all examples for all available platforms.
  generate-config             Generate config.local.h from template.
  ucx-module                  Show or set the target u-connectXpress module.
  linux.build-all             Build all examples for Linux (only available on Linux host).
  linux.http.build            Build http_example for Linux.
  linux.http.run              Build and run http_example for Linux.
  stm32.build-all             Build all STM32 examples.
  stm32.http.build            Build http_example for STM32.
  stm32.http.flash            Flash http_example to STM32 target.
  stm32.http.emulate          Run http_example in Renode emulator.
  ...

To get help for a specific task:

> invoke --help stm32.http.build
Usage: inv[oke] [--core-opts] stm32.http.build [--options] [other tasks here ...]

Docstring:
  Build http_example for STM32.

Options:
  -c, --clean                     Clean build directory before building
  -d, --docker                    Build inside Docker container (no local ARM toolchain required)
  -j STRING, --jobs=STRING        Number of parallel jobs (default: CPU cores)

Selecting a target module

Use invoke ucx-module to select the target u-connectXpress module. The selection persists across builds:

invoke ucx-module                      # Show current module and available options
invoke ucx-module --set NORA-W36X      # Set module for all subsequent builds

Building examples

Build from the examples/ directory using invoke <platform>.<example>.build:

invoke linux.http.build             # Build http_example for Linux
invoke linux.http.run               # Build and run http_example for Linux
invoke stm32.http.build --docker    # Build http_example for STM32 using Docker
invoke stm32.http.flash             # Flash http_example to STM32 hardware
invoke stm32.http.emulate           # Run http_example in Renode emulator

Build all examples:

invoke build-all --docker           # Build all examples for all platforms (STM32 via Docker)
invoke stm32.build-all --docker     # Build all STM32 examples using Docker
invoke linux.build-all              # Build all Linux examples

Or from the project root (prefix with examples.):

invoke examples.linux.http.build
invoke examples.build-all --docker

Executables are placed in examples/bin/.

Manual CMake Build

If you prefer to use CMake directly:

# From examples/ directory
> cmake -S . -B build
> cmake --build build

# Build for a specific module
> cmake -S . -B build -D UCX_MODULE=NORA-W36X
> cmake --build build

The UCX_MODULE variable selects the module-specific generated API from ucx_api/generated/<module>/. If not specified, it defaults to NORA-W36X.

Running

http_example

After building, the executable is located in bin/http_example. All arguments are optional and default to values from config.local.h:

> http_example [device] [SSID] [WPA_PSK]
  device:  the UART device connected to a u-connectXpress module (default: U_EXAMPLE_UART)
  SSID:    the Wi-Fi SSID to connect to (default: U_EXAMPLE_SSID)
  WPA_PSK: the Wi-Fi WPA PSK (default: U_EXAMPLE_WPA_PSK)

Example:

> bin/http_example                                         # Use all defaults from config.local.h
> bin/http_example /dev/ttyUSB0                            # Override device only
> bin/http_example /dev/ttyUSB0 MySSID MyWiFiPasswd        # Override all

http_example_no_os

The no-OS variant of http_example is built from the same source code but uses a different port layer (u_port_no_os.c). Because command-line arguments are typically unavailable on bare-metal targets, the UART device, Wi-Fi SSID and PSK are read from compile-time macros defined in config.local.h.

To configure, copy config.local.h.template to config.local.h and edit the values:

#define U_EXAMPLE_SSID "your-wifi-ssid"
#define U_EXAMPLE_WPA_PSK "your-wifi-password"

Then build and run:

> cmake -S . -B build
> cmake --build build
> bin/http_example_no_os

Note: Both http_example and http_example_no_os are compiled from the same http_example.c source file, demonstrating how u-connectClient examples can work seamlessly in both OS and no-OS environments.

fw_upgrade_example

This example demonstrates upgrading module firmware using the AT+USYFWUS command followed by XMODEM protocol transfer.

To run the firmware upgrade example:

> fw_upgrade_example <firmware_file> [device]
  firmware_file: path to the firmware binary file (required)
  device:        the UART device connected to a u-connectXpress module (default: U_EXAMPLE_UART)

Example:

> bin/fw_upgrade_example NORA-W36X-SW-1.0.0.bin                    # Use default device
> bin/fw_upgrade_example NORA-W36X-SW-1.0.0.bin /dev/ttyUSB0       # Specify device

The example will:

Check communication with the module
Issue the AT+USYFWUS command to enter bootloader mode
Transfer the firmware file using XMODEM protocol at 921600 baud
Wait for the module to reboot
Confirm the module is back online

fw_upgrade_example_no_os

The no-OS variant of fw_upgrade_example is built from the same source code but uses a different port layer (u_port_no_os.c). The UART device and firmware file path are configured via compile-time macros. Define them in config.local.h for a persistent setup, or provide them through CMake when configuring the build.

To pass the values through CMake:

> cd examples
> cmake -S . -B build -D U_EXAMPLE_UART="/dev/ttyUSB0" -D U_EXAMPLE_FW_FILE="NORA-W36X-SW-1.0.0.bin"
> invoke all

Then run:

> bin/fw_upgrade_example_no_os

Note: Both fw_upgrade_example and fw_upgrade_example_no_os are compiled from the same fw_upgrade_example.c source file.

ble_scan_example

This example demonstrates BLE device discovery scanning.

To run the BLE scan example:

> ble_scan_example [device]
  device: the UART device connected to a u-connectXpress module (default: U_EXAMPLE_UART)

Example:

> bin/ble_scan_example                      # Use default device from config.local.h
> bin/ble_scan_example /dev/ttyUSB0         # Specify device

The example will:

Initialize the AT client and u-connectXpress API
Query and display the module's Bluetooth MAC address
Start BLE scanning
Display discovered devices in real-time via URC callbacks
Stop scanning after the specified duration

ble_advertise_example

This example demonstrates BLE advertising with custom advertising data.

To run the BLE advertise example:

> ble_advertise_example [device] [device_name]
  device:      the UART device connected to a u-connectXpress module (default: U_EXAMPLE_UART)
  device_name: the BLE device name to advertise (default: "uCxExample")

Example:

> bin/ble_advertise_example                         # Use all defaults
> bin/ble_advertise_example /dev/ttyUSB0            # Override device only
> bin/ble_advertise_example /dev/ttyUSB0 MyDevice   # Override device and name

The example will:

Initialize the AT client and u-connectXpress API
Query and display the module's Bluetooth MAC address
Set custom advertising data (Flags + Complete Local Name "u-connectClient")
Start BLE advertising
Stop advertising after the specified duration

wifi_scan_example

This example demonstrates scanning for nearby WiFi access points.

To run the WiFi scan example:

> wifi_scan_example [device]
  device: the UART device connected to a u-connectXpress module (default: U_EXAMPLE_UART)

Example:

> bin/wifi_scan_example                     # Use default device from config.local.h
> bin/wifi_scan_example /dev/ttyUSB0        # Specify device

The example will:

Initialize the AT client and u-connectXpress API
Scan for available WiFi networks
Display each network's BSSID, SSID, channel, RSSI, and security type
Show a summary of total networks found

wifi_ap_example

This example demonstrates starting a WiFi access point (AP mode).

To run the WiFi AP example:

> wifi_ap_example [device] [SSID] [password]
  device:   the UART device connected to a u-connectXpress module (default: U_EXAMPLE_UART)
  SSID:     the AP network name (default: U_EXAMPLE_SSID)
  password: the AP password (default: U_EXAMPLE_WPA_PSK, open network if < 8 chars)

Example:

> bin/wifi_ap_example                                       # Use all defaults from config.local.h
> bin/wifi_ap_example /dev/ttyUSB0                          # Override device only
> bin/wifi_ap_example /dev/ttyUSB0 MyAP MyPassword123       # Override all

The example will:

Initialize the AT client and u-connectXpress API
Configure and start the WiFi access point
Display the AP's IP address
Monitor and display station connect/disconnect events via URCs
Run for 60 seconds then stop the AP

socket_example

This example demonstrates raw TCP socket communication.

To run the socket example:

> socket_example [device] [SSID] [WPA_PSK]
  device:  the UART device connected to a u-connectXpress module (default: U_EXAMPLE_UART)
  SSID:    the Wi-Fi SSID to connect to (default: U_EXAMPLE_SSID)
  WPA_PSK: the Wi-Fi WPA PSK (default: U_EXAMPLE_WPA_PSK)

Example:

> bin/socket_example                                        # Use all defaults from config.local.h
> bin/socket_example /dev/ttyUSB0 MySSID MyWiFiPasswd       # Override all

The example will:

Initialize the AT client and u-connectXpress API
Connect to the specified WiFi network
Create a TCP socket and connect to httpbin.org:80
Send an HTTP GET request
Receive and display the response using URC-driven data availability events
Close the socket and disconnect from WiFi

Navigation Menu

Repository navigation

README.md

README.md

Examples

Configuration

Building

Available platforms

Listing available tasks

Selecting a target module

Building examples

Manual CMake Build

Running

http_example

http_example_no_os

fw_upgrade_example

fw_upgrade_example_no_os

ble_scan_example

ble_advertise_example

wifi_scan_example

wifi_ap_example

socket_example

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Examples

Configuration

Building

Available platforms

Listing available tasks

Selecting a target module

Building examples

Manual CMake Build

Running

http_example

http_example_no_os

fw_upgrade_example

fw_upgrade_example_no_os

ble_scan_example

ble_advertise_example

wifi_scan_example

wifi_ap_example

socket_example