1.. _module-pw_router: 2 3--------- 4pw_router 5--------- 6.. pigweed-module:: 7 :name: pw_router 8 9The ``pw_router`` module provides transport-agnostic classes for routing packets 10over network links. 11 12Common router interfaces 13======================== 14 15.. _module-pw_router-packet_parser: 16 17PacketParser 18------------ 19To work with arbitrary packet formats, routers require a common interface for 20extracting relevant packet data, such as the destination. This interface is 21``pw::router::PacketParser``, defined in ``pw_router/packet_parser.h``, which 22must be implemented for the packet framing format used by the network. 23 24.. _module-pw_router-egress: 25 26Egress 27------ 28The Egress class is a virtual interface for sending packet data over a network 29link. Egress implementations provide a single ``SendPacket`` function, which 30takes the raw packet data and transmits it. 31 32Egresses are invoked with the ``PacketParser`` used to process the packet. This 33allows additional information to be extracted from each packet to assist with 34transmitting decisions. For example, if packets in a project include a priority, 35egresses may use it to provide quality-of-service by dropping certain packets 36under heavy load. 37 38.. code-block:: c++ 39 40 Status MyEgress::SendPacket( 41 ConstByteSpan packet, const PacketParser& parser) override { 42 // Downcast the base PacketParser to the custom implementation that was 43 // passed into RoutePacket(). 44 const CustomPacketParser& custom_parser = 45 static_cast<const CustomPacketParser&>(parser); 46 47 // Custom packet fields can now be accessed if necessary. 48 if (custom_parser.priority() == MyPacketPriority::kHigh) { 49 return SendHighPriorityPacket(packet); 50 } 51 52 return SendStandardPriorityPacket(packet); 53 } 54 55Some common egress implementations are provided upstream in Pigweed. 56 57.. _module-pw_router-static_router: 58 59StaticRouter 60============ 61``pw::router::StaticRouter`` is a router with a static table of address to 62egress mappings. Routes in a static router never change; packets with the same 63address are always sent through the same egress. If links are unavailable, 64packets will be dropped. 65 66Static routers are suitable for basic networks with persistent links. 67 68Usage example 69------------- 70 71.. code-block:: c++ 72 73 namespace { 74 75 // Define the router egresses. 76 UartEgress uart_egress; 77 BluetoothEgress ble_egress; 78 79 // Define the routing table. 80 constexpr pw::router::StaticRouter::Route routes[] = {{1, uart_egress}, 81 {7, ble_egress}}; 82 pw::router::StaticRouter router(routes); 83 84 } // namespace 85 86 void ProcessPacket(pw::ConstByteSpan packet) { 87 HdlcFrameParser hdlc_parser; 88 router.RoutePacket(packet, hdlc_parser); 89 } 90 91Size report 92----------- 93The following size report shows the cost of a ``StaticRouter`` with a simple 94``PacketParser`` implementation and a single route using an ``EgressFunction``. 95 96.. include:: static_router_size 97 98Zephyr 99====== 100To enable ``pw_router.*`` for Zephyr add ``CONFIG_PIGWEED_ROUTER=y`` to the 101project's configuration. This will enable the Kconfig menu for the following: 102 103* ``pw_router.static_router`` which can be enabled via 104 ``CONFIG_PIGWEED_ROUTER_STATIC_ROUTER=y``. 105* ``pw_router.egress`` which can be enabled via 106 ``CONFIG_PIGWEED_ROUTER_EGRESS=y``. 107* ``pw_router.packet_parser`` which can be enabled via 108 ``CONFIG_PIGWEED_ROUTER_PACKET_PARSER=y``. 109* ``pw_router.egress_function`` which can be enabled via 110 ``CONFIG_PIGWEED_ROUTER_EGRESS_FUNCTION=y``. 111