pw_hdlc: RPC over HDLC example project#

Pigweed AI summary: The pw_hdlc module includes an example of bringing up an RPC server that can be used to invoke RPCs. The example code is located at pw_hdlc/rpc_example. The instructions assume the STM32F429i Discovery board, but they work with any target with pw::sys_io implemented. The example can be invoked interactively or with a script. The local RPC example project is similar to the above example, except it uses a socket to connect a server and a client running on the

The pw_hdlc module includes an example of bringing up a pw_rpc server that can be used to invoke RPCs. The example code is located at pw_hdlc/rpc_example. This section walks through invoking RPCs interactively and with a script using the RPC over HDLC example.

These instructions assume the STM32F429i Discovery board, but they work with any target with pw::sys_io implemented.

Getting started guide#

Pigweed AI summary: This guide provides instructions for setting up and using Pigweed, a collection of libraries and tools for building embedded systems. The guide covers connecting the board, building Pigweed, flashing the firmware image, invoking RPCs from an interactive console, and invoking RPCs with a script. The guide includes code snippets and commands to execute.

1. Set up your board#

Pigweed AI summary: To set up your board for communication, connect it using the mini USB port and take note of the serial device it appears as, such as "/dev/ttyACM0" for the Discovery board.

Connect the board you’ll be communicating with. For the Discovery board, connect the mini USB port, and note which serial device it appears as (e.g. /dev/ttyACM0).

2. Build Pigweed#

Pigweed AI summary: This section provides instructions on how to build Pigweed by activating the Pigweed environment and running the default build. The process involves installing nanopb, generating the necessary files, and using ninja to build the project.

Activate the Pigweed environment and run the default build.

. ./activate.sh
pw package install nanopb
gn gen out --args='dir_pw_third_party_nanopb="//environment/packages/nanopb"'
ninja -C out

3. Flash the firmware image#

Pigweed AI summary: This section provides instructions on how to flash the firmware image to a board after a successful build. The binary for the example will be located in a specific directory and can be flashed using OpenOCD if using the STM32F429i Discovery Board. The section includes a literal block of code with the necessary commands to flash the image.

After a successful build, the binary for the example will be located at out/<toolchain>/obj/pw_hdlc/rpc_example/bin/rpc_example.elf.

Flash this image to your board. If you are using the STM32F429i Discovery Board, you can flash the image with OpenOCD.

openocd -f \
  targets/stm32f429i_disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg \
  -c "program \
  out/stm32f429i_disc1_debug/obj/pw_hdlc/rpc_example/bin/rpc_example.elf \
  verify reset exit"

4. Invoke RPCs from in an interactive console#

Pigweed AI summary: The RPC console uses pw_console to create an interactive console for working with pw_rpc. To run the RPC console, use the command provided, replacing the serial device with the correct one for your board. RPCs can be accessed through the predefined "rpcs" variable, organized by their protocol buffer package and RPC service. To call the Echo method of the EchoService in the pw.rpc package, use the provided code block.

The RPC console uses pw_console to make a rich interactive console for working with pw_rpc. Run the RPC console with the following command, replacing /dev/ttyACM0 with the correct serial device for your board.

pw-system-console --no-rpc-logging --proto-globs pw_rpc/echo.proto \
  --device /dev/ttyACM0

RPCs may be accessed through the predefined rpcs variable. RPCs are organized by their protocol buffer package and RPC service, as defined in a .proto file. To call the Echo method is part of the EchoService, which is in the pw.rpc package. To invoke it synchronously, call rpcs.pw.rpc.EchoService.Echo:

>>> device.rpcs.pw.rpc.EchoService.Echo(msg='Hello, world!')
(Status.OK, pw.rpc.EchoMessage(msg='Hello, world!'))

5. Invoke RPCs with a script#

Pigweed AI summary: This section explains how to invoke RPCs from Python scripts. The example script provided should be executed after closing the RPC console and setting the –device argument to the serial port for the device. The expected output includes the status, payload, and device response.

RPCs may also be invoked from Python scripts. Close the RPC console if it is running, and execute the example script. Set the –device argument to the serial port for your device.

python pw_hdlc/rpc_example/example_script.py --device /dev/ttyACM0

You should see this output:

The status was Status.OK
The payload was msg: "Hello"

The device says: Goodbye!

Local RPC example project#

Pigweed AI summary: This example project uses a socket to connect a server and a client running on the same host. To start, activate the Pigweed environment and build the code. Then, run the pw_rpc server in one terminal window and the pw-system-console RPC client in another activated terminal window. The client can invoke RPCs from the interactive console, and the default RPC Channel ID can be overridden with --channel-id. Additional information on using the pw_console UI and other RPC enabled application examples can be found in the

This example is similar to the above example, except it uses a socket to connect a server and a client running on the host.

1. Build Pigweed#

Pigweed AI summary: To build Pigweed, the Pigweed environment must be activated and the code must be built. This can be done by installing nanopb and generating the code with gn gen out. Finally, the code can be built using ninja -C out.

Activate the Pigweed environment and build the code.

. ./activate.sh
pw package install nanopb
gn gen out --args='dir_pw_third_party_nanopb="//environment/packages/nanopb"'
ninja -C out

2. Start client side and server side#

Pigweed AI summary: This section provides instructions on how to start the client side and server side for RPC communication. The pw_rpc server should be run in one terminal window, while the pw-system-console RPC client should be run in a separate activated terminal with the --proto-globs set to pw_rpc/echo.proto. The default RPC Channel ID can be overridden with --channel-id. The interactive console on the client side can then be used to invoke RPCs. The section also provides links to additional documentation on using the pw

Run pw_rpc server in one terminal window.

./out/pw_strict_host_clang_debug/obj/pw_hdlc/rpc_example/bin/rpc_example

In a separate activated terminal, run the pw-system-console RPC client with --proto-globs set to pw_rpc/echo.proto. Additional protos can be added if needed.

pw-system-console --no-rpc-logging --proto-globs pw_rpc/echo.proto \
  --socket-addr default

Tip

The --socket-addr may be replaced with IP and port separated by a colon, for example: 127.0.0.1:33000; or, if using a unix socket, the path to the file follows “file:”, for example file:/path/to/unix/socket. Unix socket Python support is pending https://bugs.python.org/issue33408.

Tip

The default RPC Channel ID (1) can be overriden with --channel-id.

Then you can invoke RPCs from the interactive console on the client side.

>>> device.rpcs.pw.rpc.EchoService.Echo(msg='Hello, world!')
(Status.OK, pw.rpc.EchoMessage(msg='Hello, world!'))