Skip to main content
Version: 2.8.0

Routing Table

caution

Make sure you have read and understood the network topoly section before reading this page.

The routing table is a feature of Luos allowing every servicesSoftware element run by Luos that can communicate with other services. It can be a driver or an app. to own a "map" (or topology) of the entire network of your device. This map enables services to know their physical position and to search and interact with other services quickly.

This feature is particularly used by app services to find other services they need to interact with. The routing table is shared by the service that launches the detection to other services.

Detection​

The routing table is automatically generated when a service requires Luos engine to initiate a network detection. It is then shared with other services at the end of the detection. Any service can require a detection, but driver services should not do it; this features should be only used with app services by including routingTable.h and using this routing table API.

To run a detection, type:

Luos_Detect(app);

where app is the service_t pointer running the detection.

A non-detected service (not in the routing table) has a specific ID of 0. At the beginning of the detection, Luos engine erases each service's ID in the network, so all of them will have ID 0 during this operation. You can use it on your services' code to act consequently to this detection if you need it (for example, a service can monitor its ID to detect if a detection has been made and if it has to reconfigure its auto-update).

Then the service running the detection will have ID 1, and the other services will have an ID between 2 and 4096, depending on their position from the service detector. IDs are attributed to the services according to their position from the detector service, and to the branch they are in. IDs' attribution begins first to the PTPA port, then PTPB, etc. When each service in the network has an attributed ID, the detection algorithm proceeds to create the routing table and shares it with every service (saved only one time per node).

Sometimes, multiple services in the network can have the same alias, which is not allowed to prevent service confusion. In this case, the detection algorithm will add an incremented number after each alias instance in the routing table.

At the end of the detection process, each service receives a message with the command of END_DETECTION, that can be used in your code in order to understand the exact moment when the detection has finished, and you can then reinitialize the behavior of your services (for example reinitialize the auto-updates, etc.). Also, you can check the detection status of your node, by using the dedicated Luos engine's API:

Luos_IsNodeDetected();

It returns true or false depending on whether this node is detected or not.

caution

Warnings:

  1. Be careful that a service's ID can change during a detection depending on the service running this detection.
  2. Do not consider your service's ID fixed.
  3. Be aware that every service removes its auto-update configuration during the detection to prevent any ID movement.
  4. Make sure that by the creation of your services you specified a callback pointer for each of them, so that the messages arriving to them concerning the detection do not stay stored in your node's memory. :::

Modes​

Nodes can host multiple services. To get the topology of your device, the routing table references physical connections between the nodes and lists all the services in each one of them.

The routing table is a table of a routing_table_t structure containing nodes or services information. The precompilation constant MAX_SERVICES_NUMBER manages the maximum number of services (set to 40 by default).

routing_table_t routing_table[MAX_SERVICES_NUMBER];

The routing table structure has two modes: service entry mode and node entry mode.

typedef struct __attribute__((__packed__))
{
    uint8_t mode; // entry_mode_t
    union
    {
        struct __attribute__((__packed__))
        {                               // SERVICE mode entry
            uint16_t id;                // Service ID.
            uint16_t type;              // Service type.
            uint8_t access;             // Service Access access_t
            char alias[MAX_ALIAS_SIZE]; // Service alias.
        };
        struct __attribute__((__packed__))
        { // NODE mode entry
            // Watch out this structure have a lot similarities with the node_t struct.
            // It is similar to allow copy of a node_t struct directly in this one.
            // But you there is potentially a port_table size difference so
            // Do not replace it with node_t struct.
            struct __attribute__((__packed__))
            {
                uint16_t node_id : 12;  // Node id
                uint16_t certified : 4; // True if the node have a certificate
                uint8_t node_info;      // node info can contain info such as the saving of routing table
            };
            uint16_t port_table[(MAX_ALIAS_SIZE + 2 + 2 + sizeof(uint8_t) - 2) / 2]; // Node link table
        };
        uint8_t unmap_data[MAX_ALIAS_SIZE + 2 + 2 + sizeof(uint8_t)];
    };
} routing_table_t;

Service entry mode​

Service entry mode allows the routing table to include information about a service. As a node can host one or more services, the routing table is able to obtain the specific information for each one of them:

  • id: service's unique id
  • type: service's type
  • alias: service's alias

You can read the services page for more information about what services are and how they are used.

Node entry mode​

This mode gives physical information about your devices.

The node_id is the unique number that you can use to identify each one of your nodes. At the beginning (or when a reset detection is performed), all node IDs are set to 0. When the RoutingTB_DetectServices API is called, Luos engine assigns a unique ID to nodes and services in your system topology.

The Luos node can be certified in your system to guarantee the security and integrity of your network, by including the Luos engine's licencing number in your product (feature in progress).

The port_table allows the sharing of topological information of your network. Each element of this table corresponds to a physical network port of the node and indicates which node is connected to it by sharing a node's id.

Here is an example:

luos_imgluos_img

As shown on this image, elements of the port_table indicate the first or last service's ID of the connected node through a given port.

Specific values can be taken by port_table:

  • 0: this port is waiting to discover which is connected with. You should never see this value.
  • 0x0FFF: this port is not connected to any other node.

Routing tables can be easily displayed using Pyluos through a USB gate. Please refer to the Pyluos routing table section for more information. :::

The routing table library provides filtering tools to find the services and nodes' information into a Luos network. In order to use these filtering functions, you need to define a search_result_t variable, where you will store the filtered information.

The search_result_t structure includes a list of the routing table entries, as well as a number that indicates the number of services that it contains:

typedef struct
{
    uint16_t result_nbr;
    routing_table_t *result_table[MAX_RTB_ENTRY];
} search_result_t;

First of all, we need to reset the filtering result in order to contain all the services existing in the routing table. Afterwords, we can filter the routing table entries, depending on a specific characteristic of the services like the type, the alias, etc.

Here is an example:

luos_imgluos_img

Having access to the different services' information existing in the filtering result is done with the code result.result_table[i]->id or result.result_table[i]->type, as each result_table[] is a routing table entry.

All the filtering APIs are listed below:

DescriptionFunctionReturn
Reset the results tableRTFilter_Reset(search_result_t *result);search_result_t*
Find a the service of a specific idRTFilter_ID(search_result_t *result, uint16_t id);search_result_t*
Find the services of a specific typeRTFilter_Type(search_result_t *result, luos_type_t type);search_result_t*
Find the services of a specific nodeRTFilter_Node(search_result_t *result, uint16_t node_id);search_result_t*
Find the services of a specific aliasRTFilter_Alias(search_result_t *result, char* alias);search_result_t*
Find the service of a specific service pointerRTFilter_Service(search_result_t *result, service_t *service);search_result_t*