1 .. _module-pw_hdlc_lite-rpc-example:
3 =============================
4 RPC over HDLC example project
5 =============================
6 The :ref:`module-pw_hdlc_lite` module includes an example of bringing up a
7 :ref:`module-pw_rpc` server that can be used to invoke RPCs. The example code
8 is located at ``pw_hdlc_lite/rpc_example``. This section walks through invoking
9 RPCs interactively and with a script using the RPC over HDLC example.
11 These instructions assume the STM32F429i Discovery board, but they work with
12 any target with :ref:`pw::sys_io <module-pw_sys_io>` implemented.
20 Connect the board you'll be communicating with. For the Discovery board, connect
21 the mini USB port, and note which serial device it appears as (e.g.
26 Activate the Pigweed environment and run the default build.
34 3. Flash the firmware image
35 ===========================
36 After a successful build, the binary for the example will be located at
37 ``out/<toolchain>/obj/pw_hdlc_lite/rpc_example/bin/rpc_example.elf``.
39 Flash this image to your board. If you are using the STM32F429i Discovery Board,
40 you can flash the image with `OpenOCD <http://openocd.org>`_.
44 openocd -f targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg \
45 -c "program out/stm32f429i_disc1_debug/obj/pw_hdlc_lite/rpc_example/bin/rpc_example.elf"
47 4. Invoke RPCs from in an interactive console
48 =============================================
49 The RPC console uses `IPython <https://ipython.org>`_ to make a rich interactive
50 console for working with pw_rpc. Run the RPC console with the following command,
51 replacing ``/dev/ttyACM0`` with the correct serial device for your board.
55 $ python -m pw_hdlc_lite.rpc_console --device /dev/ttyACM0
57 Console for interacting with pw_rpc over HDLC.
59 To start the console, provide a serial port as the --device argument and paths
60 or globs for .proto files that define the RPC services to support:
62 python -m pw_hdlc_lite.rpc_console --device /dev/ttyUSB0 sample.proto
64 This starts an IPython console for communicating with the connected device. A
65 few variables are predefined in the interactive console. These include:
67 rpcs - used to invoke RPCs
68 device - the serial device used for communication
69 client - the pw_rpc.Client
71 An example echo RPC command:
73 rpcs.pw.rpc.EchoService.Echo(msg="hello!")
77 RPCs may be accessed through the predefined ``rpcs`` variable. RPCs are
78 organized by their protocol buffer package and RPC service, as defined in a
79 .proto file. To call the ``Echo`` method is part of the ``EchoService``, which
80 is in the ``pw.rpc`` package. To invoke it synchronously, call
81 ``rpcs.pw.rpc.EchoService.Echo``:
83 .. code-block:: python
85 In [1]: rpcs.pw.rpc.EchoService.Echo(msg="Your message here!")
86 Out[1]: (<Status.OK: 0>, msg: "Your message here!")
88 5. Invoke RPCs with a script
89 ============================
90 RPCs may also be invoked from Python scripts. Close the RPC console if it is
91 running, and execute the example script. Set the --device argument to the
92 serial port for your device.
96 $ pw_hdlc_lite/rpc_example/example_script.py --device /dev/ttyACM0
97 The status was Status.OK
98 The payload was msg: "Hello"
100 The device says: Goodbye!