1.. _target-host-device-simulator: 2 3===================== 4Host Device Simulator 5===================== 6This Pigweed target simulates the behavior of an embedded device, spawning 7threads for facilities like RPC and logging. Executables built by this target 8will perpetually run until they crash or are explicitly terminated. All 9communications with the process are over the RPC server hosted on a local 10socket rather than by directly interacting with the terminal via standard I/O. 11Host Device Simulator is built on top of :ref:`module-pw_system`. 12 13----- 14Setup 15----- 16.. _Kudzu: https://pigweed.googlesource.com/pigweed/kudzu/+/refs/heads/main/targets/host/BUILD.gn 17 18.. note:: 19 20 The instructions below show you how to try out Host Device Simulator within 21 an :ref:`upstream Pigweed environment <docs-get-started-upstream>`. To set 22 up a target *similar* to Host Device Simulator in your own project, see 23 `Kudzu`_. 24 25To use this target, Pigweed must be set up to use Nanopb and FreeRTOS. The 26required source repositories can be downloaded via ``pw package``, and then the 27build must be manually configured to point to the location the repository was 28downloaded to using gn args. 29 30.. code-block:: console 31 32 pw package install nanopb 33 pw package install freertos 34 35 gn gen out --export-compile-commands --args=" 36 dir_pw_third_party_nanopb=\"$PW_PROJECT_ROOT/environment/packages/nanopb\" 37 dir_pw_third_party_freertos=\"$PW_PROJECT_ROOT/environment/packages/freertos\" 38 " 39 40.. tip:: 41 42 Instead of the ``gn gen out`` with args set on the command line above you can 43 run: 44 45 .. code-block:: console 46 47 gn args out 48 49 Then add the following lines to that text file: 50 51 .. code-block:: 52 53 dir_pw_third_party_nanopb = getenv("PW_PACKAGE_ROOT") + "/nanopb" 54 dir_pw_third_party_freertos = getenv("PW_PACKAGE_ROOT") + "/freertos" 55 56----------------------------- 57Building and running the demo 58----------------------------- 59.. _//sample_project_tools/device_sim.py: https://pigweed.googlesource.com/pigweed/sample_project/+/refs/heads/main/tools/sample_project_tools/device_sim.py 60 61.. tip:: 62 63 See `//sample_project_tools/device_sim.py`_ for a more polished example 64 of running a simulated device. ``device_sim.py`` runs the simulated device 65 as a subprocess and then connects to it via the default socket so you just 66 have to pass the binary. 67 68To build the demo application: 69 70.. code-block:: console 71 72 ninja -C out pw_system_demo 73 74To run the demo application: 75 76.. code-block:: console 77 78 ./out/host_device_simulator.speed_optimized/obj/pw_system/bin/system_example 79 80To communicate with the launched process run this in a separate shell: 81 82.. code-block:: console 83 84 pw-system-console -s default --proto-globs pw_rpc/echo.proto 85 86Exit the console via the GUI menu or by pressing :kbd:`Ctrl-D` twice. 87 88To stop the ``system_example`` app on Linux / macOS: 89 90.. code-block:: console 91 92 killall system_example 93 94----------- 95Communicate 96----------- 97In the bottom-most pane labeled ``Python Repl`` you should be able to send RPC 98commands to the simulated device process. 99 100To send an RPC message that will be echoed back: 101 102.. code-block:: pycon 103 104 >>> device.rpcs.pw.rpc.EchoService.Echo(msg='Hello, world!') 105 (Status.OK, pw.rpc.EchoMessage(msg='Hello, world!')) 106 107To run unit tests included on the simulated device: 108 109.. code-block:: pycon 110 111 >>> device.run_tests() 112 True 113 114You are now up and running! 115 116.. seealso:: 117 118 The :ref:`module-pw_console` 119 :bdg-ref-primary-line:`module-pw_console-user_guide` for more info on using 120 the the pw_console UI. 121