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