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.. _examples repo: https://pigweed.googlesource.com/pigweed/examples/+/refs/heads/main/ 18 19.. note:: 20 21 The instructions below show you how to try out Host Device Simulator within 22 an :ref:`upstream Pigweed environment <docs-get-started-upstream>`. To set 23 up a target *similar* to Host Device Simulator in your own project, see 24 `Kudzu`_ or the `examples repo`_. 25 26.. tab-set:: 27 28 .. tab-item:: Bazel 29 :sync: bazel 30 31 No extra setup steps are required for Bazel. 32 33 .. tab-item:: GN 34 :sync: gn 35 36 To use this target, Pigweed must be set up to use Nanopb and FreeRTOS. The 37 required source repositories can be downloaded via ``pw package``, and 38 then the build must be manually configured to point to the location the 39 repository was downloaded to using gn args. 40 41 .. code-block:: console 42 43 pw package install nanopb 44 pw package install freertos 45 46 gn gen out --export-compile-commands --args=" 47 dir_pw_third_party_nanopb=\"//environment/packages/nanopb\" 48 dir_pw_third_party_freertos=\"//environment/packages/freertos\" 49 " 50 51 .. tip:: 52 53 Instead of the ``gn gen out`` with args set on the command line above 54 you can run: 55 56 .. code-block:: console 57 58 gn args out 59 60 Then add the following lines to that text file: 61 62 .. code-block:: 63 64 dir_pw_third_party_nanopb = "//environment/packages/nanopb" 65 dir_pw_third_party_freertos = "//environment/packages/freertos" 66 67 68.. _target-host-device-simulator-demo: 69 70----------------------------- 71Building and running the demo 72----------------------------- 73.. _examples repo device_sim.py: https://pigweed.googlesource.com/pigweed/examples/+/refs/heads/main/tools/sample_project_tools/device_sim.py 74.. _Pigweed upstream device_sim.py: https://cs.opensource.google/pigweed/pigweed/+/main:pw_system/py/pw_system/device_sim.py 75 76.. seealso:: 77 78 See the `examples repo device_sim.py`_ for a downstream project example of 79 launching a device simulator with project specific RPC protos. That script 80 uses `Pigweed upstream device_sim.py`_ which runs the simulated device as a 81 subprocess and then connects to it via the default socket so you just have to 82 pass the binary. 83 84.. tab-set:: 85 86 .. tab-item:: Bazel 87 :sync: bazel 88 89 Build and run the demo application console with: 90 91 .. code-block:: console 92 93 bazel run //pw_system:simulator_system_example_console 94 95 .. tab-item:: GN 96 :sync: gn 97 98 Build the demo application: 99 100 .. code-block:: console 101 102 ninja -C out pw_system_demo 103 104 Launch the demo application and connect to it with the pw_system console: 105 106 .. code-block:: console 107 108 pw-system-device-sim \ 109 --sim-binary \ 110 ./out/host_device_simulator.speed_optimized/obj/pw_system/bin/system_example 111 112Exit the console via the GUI menu, running ``exit`` or ``quit`` in the Python 113repl or by pressing :kbd:`Ctrl-D` twice. 114 115----------- 116Communicate 117----------- 118In the bottom-most pane labeled ``Python Repl`` you should be able to send RPC 119commands to the simulated device process. 120 121To send an RPC message that will be echoed back: 122 123.. code-block:: pycon 124 125 >>> device.rpcs.pw.rpc.EchoService.Echo(msg='Hello, world!') 126 (Status.OK, pw.rpc.EchoMessage(msg='Hello, world!')) 127 128To run unit tests included on the simulated device: 129 130.. code-block:: pycon 131 132 >>> device.run_tests() 133 True 134 135You are now up and running! 136 137.. seealso:: 138 139 The :ref:`module-pw_console` 140 :bdg-ref-primary-line:`module-pw_console-user_guide` for more info on using 141 the the pw_console UI. 142