1.. _module-pw_rpc: 2 3====== 4pw_rpc 5====== 6.. pigweed-module:: 7 :name: pw_rpc 8 9.. tab-set:: 10 11 12 .. tab-item:: blinky.proto 13 14 .. code-block:: protobuf 15 16 /* //applications/blinky/blinky.proto */ 17 18 syntax = "proto3"; 19 20 package blinky; 21 22 import "pw_protobuf_protos/common.proto"; 23 24 service Blinky { 25 // Toggles the LED on or off. 26 rpc ToggleLed(pw.protobuf.Empty) returns (pw.protobuf.Empty); 27 // Continuously blinks the board LED a specified number of times. 28 rpc Blink(BlinkRequest) returns (pw.protobuf.Empty); 29 } 30 31 message BlinkRequest { 32 // The interval at which to blink the LED, in milliseconds. 33 uint32 interval_ms = 1; 34 // The number of times to blink the LED. 35 optional uint32 blink_count = 2; 36 } // BlinkRequest 37 38 .. tab-item:: main.cc 39 40 .. code-block:: cpp 41 42 /* //applications/blinky/main.cc */ 43 44 // ... 45 #include "applications/blinky/blinky.rpc.pb.h" 46 #include "pw_system/rpc_server.h" 47 // ... 48 49 class BlinkyService final 50 : public blinky::pw_rpc::nanopb::Blinky::Service<BlinkyService> { 51 public: 52 pw::Status ToggleLed(const pw_protobuf_Empty &, pw_protobuf_Empty &) { 53 // Turn the LED off if it's currently on and vice versa 54 } 55 pw::Status Blink(const blinky_BlinkRequest &request, pw_protobuf_Empty &) { 56 if (request.blink_count == 0) { 57 // Stop blinking 58 } 59 if (request.interval_ms > 0) { 60 // Change the blink interval 61 } 62 if (request.has_blink_count) { // Auto-generated property 63 // Blink request.blink_count times 64 } 65 } 66 }; 67 68 BlinkyService blinky_service; 69 70 namespace pw::system { 71 72 void UserAppInit() { 73 // ... 74 pw::system::GetRpcServer().RegisterService(blinky_service); 75 } 76 77 } // namespace pw::system 78 79 .. tab-item:: BUILD.bazel 80 81 .. code-block:: python 82 83 # //applications/blinky/BUILD.bazel 84 85 load( 86 "@pigweed//pw_protobuf_compiler:pw_proto_library.bzl", 87 "nanopb_proto_library", 88 "nanopb_rpc_proto_library", 89 ) 90 91 cc_binary( 92 name = "blinky", 93 srcs = ["main.cc"], 94 deps = [ 95 ":nanopb_rpc", 96 # ... 97 "@pigweed//pw_system", 98 ], 99 ) 100 101 proto_library( 102 name = "proto", 103 srcs = ["blinky.proto"], 104 deps = [ 105 "@pigweed//pw_protobuf:common_proto", 106 ], 107 ) 108 109 nanopb_proto_library( 110 name = "nanopb", 111 deps = [":proto"], 112 ) 113 114 nanopb_rpc_proto_library( 115 name = "nanopb_rpc", 116 nanopb_proto_library_deps = [":nanopb"], 117 deps = [":proto"], 118 ) 119 120.. grid:: 2 121 122 .. grid-item-card:: :octicon:`rocket` Quickstart & guides 123 :link: module-pw_rpc-guides 124 :link-type: ref 125 :class-item: sales-pitch-cta-primary 126 127 Check out the ``pw_rpc`` quickstart for more explanation of the code above. 128 The guides answer common questions such as whether 129 to use ``proto2`` or ``proto3`` syntax. 130 131 .. grid-item-card:: :octicon:`code-square` C++ server and client 132 :link: module-pw_rpc-cpp 133 :link-type: ref 134 :class-item: sales-pitch-cta-secondary 135 136 C++ server and client library API guides. 137 138.. grid:: 2 139 140 .. grid-item-card:: :octicon:`info` Packet protocol 141 :link: module-pw_rpc-protocol 142 :link-type: ref 143 :class-item: sales-pitch-cta-secondary 144 145 A detailed description of the ``pw_rpc`` packet protocol. 146 147 .. grid-item-card:: :octicon:`info` Design 148 :link: module-pw_rpc-design 149 :link-type: ref 150 :class-item: sales-pitch-cta-secondary 151 152 An overview of the RPC call lifecycle, naming conventions, 153 and the ``pw_rpc`` roadmap. 154 155.. grid:: 2 156 157 .. grid-item-card:: :octicon:`code-square` Python client 158 :link: module-pw_rpc-py 159 :link-type: ref 160 :class-item: sales-pitch-cta-secondary 161 162 Python client library API reference. 163 164 .. grid-item-card:: :octicon:`code-square` TypeScript client 165 :link: module-pw_rpc-ts 166 :link-type: ref 167 :class-item: sales-pitch-cta-secondary 168 169 TypeScript client library API guide. 170 171.. grid:: 2 172 173 .. grid-item-card:: :octicon:`code-square` Nanopb codegen 174 :link: module-pw_rpc_nanopb 175 :link-type: ref 176 :class-item: sales-pitch-cta-secondary 177 178 Nanopb codegen library API guide. 179 180 .. grid-item-card:: :octicon:`code-square` pw_protobuf codegen 181 :link: module-pw_rpc_pw_protobuf 182 :link-type: ref 183 :class-item: sales-pitch-cta-secondary 184 185 ``pw_protobuf`` codegen library API guide. 186 187.. toctree:: 188 :maxdepth: 1 189 :hidden: 190 191 guides 192 libraries 193 protocol 194 design 195 HDLC example <../pw_hdlc/rpc_example/docs> 196