158 lines
6.3 KiB
ReStructuredText
158 lines
6.3 KiB
ReStructuredText
Remote Controlled Item Router
|
|
=============================
|
|
|
|
The router script runs on a Lua Controlled Sorting Tube and allows another node
|
|
on a Digiline network to remotely control routing of items.
|
|
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
``unroutable``
|
|
This string is the colour where items should be sent if they cannot be
|
|
routed properly according to the instructions received so far from the
|
|
Digiline network. Sending items to this destination indicates an error.
|
|
|
|
``channel``
|
|
This string is the Digiline channel on which routing instructions are
|
|
received and to which notifications and replies are sent.
|
|
|
|
|
|
Operational Overview
|
|
--------------------
|
|
|
|
The router maintains an internal routing table, keyed by item name (in
|
|
Minetest-internal form, e.g. ``default:cobble``). Unlike routing tables in, for
|
|
example, IP networks, the routing table in a remote controlled item router
|
|
contains entries that only apply to a certain number of items—for example, a
|
|
routing table entry might specify “please send seven ``default:cobble`` in the
|
|
red direction”. In a typical system, a controller will determine that a
|
|
particular number of a particular item needs to reach a particular destination,
|
|
then add routing table entries to the routers along the path to ensure the
|
|
items reach their destination. If the same item is needed in two places,
|
|
entries can be added simultaneously for both destinations; as items pass
|
|
through the system, they will go to one destination or the other, up to the
|
|
specified count in each direction, eventually delivering the proper number of
|
|
items to both destinations.
|
|
|
|
If a stack of more than one item arrives at the router, it will be sent to some
|
|
destination that has routing table entries adding up to at least the stack
|
|
size. The router will never send more items to a destination than the total
|
|
requested, though if the table has multiple entries for the same destination, a
|
|
single stack may contribute to more than one entry; for example, if there are
|
|
two three-item requests for the same item to the same colour, a single six-item
|
|
stack could be routed to that colour, but a seven-item stack would not. Because
|
|
stacks cannot be split, an overly large stack may generate an error; for
|
|
example, if there are two three-item requests for the same item to two
|
|
different directions, a single six-item stack would generate an error and be
|
|
sent to the unroutable colour because it cannot be split into two smaller
|
|
stacks. The system injecting item stacks into the routing network is expected
|
|
to act accordingly.
|
|
|
|
|
|
Digiline Message Structure
|
|
--------------------------
|
|
|
|
All messages sent to or from the router must be table-typed messages. Messages
|
|
are divided into commands and responses: commands are sent to the router while
|
|
responses are returned from the router. All command messages contain a key
|
|
named ``command`` with a string value identifying the nature of the command.
|
|
All response messages contain a key named ``response`` with a string value
|
|
identifying the nature of the response. Other keys contain additional
|
|
information whose meaning depends on the command or response.
|
|
|
|
|
|
``clear`` Command
|
|
-----------------
|
|
|
|
This command removes all routing table entries. No parameters are needed nor is
|
|
a reply generated. `Done response`_ messages are *not* sent for the removed
|
|
entries.
|
|
|
|
|
|
``query`` Command
|
|
-----------------
|
|
|
|
This command causes a `query_reply response`_ to be returned. No parameters are
|
|
needed.
|
|
|
|
|
|
``route`` Command
|
|
-----------------
|
|
|
|
This command adds one or more entries to the routing table. In addition to
|
|
having a ``command`` key, the message must also be an array—in other words, a
|
|
table with consecutive integer keys starting from 1. These array entries are
|
|
interpreted in order, with each entry being a routing table entry to add.
|
|
|
|
Routing Table Entry
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
An individual routing table entry in the ``route`` command is formatted as a
|
|
table. Within the table, the following keys are understood:
|
|
|
|
``name``
|
|
This string is the Minetest-internal name of the item to route (e.g.
|
|
``default:cobble``). This key is required.
|
|
|
|
``count``
|
|
This number is how many items the entry applies to. Once this many of the
|
|
specified item have been routed according to this entry, the entry expires
|
|
and is removed from the table. This key is required.
|
|
|
|
``direction``
|
|
This string is the colour indicating which direction to send the items.
|
|
This key is required.
|
|
|
|
``id``
|
|
This value (of any type) is returned in a `done response`_ when the entry
|
|
expires and can be used by the controller to distinguish entries. The value
|
|
is not interpreted in any way, so the controller may supply any value. This
|
|
key is optional; if not provided, the entry expires silently without a
|
|
`done response`_ being returned.
|
|
|
|
|
|
``done`` Response
|
|
-----------------
|
|
|
|
This response informs the user that a routing table entry has expired. In
|
|
addition to the ``response`` key, the message also contains an ``id`` key,
|
|
which is set to the ``id`` value provided when the routing table entry was
|
|
initially added.
|
|
|
|
|
|
``query_reply`` Response
|
|
------------------------
|
|
|
|
This response reports a summary of all entries in the routing table and is only
|
|
sent in response to a `query command`_. In addition to the ``response`` key,
|
|
the message also contains an ``items`` key, whose value is a table keyed by
|
|
item name. Each item name maps to another table whose keys are the six
|
|
directional colours (all six are always present). Each colour maps to a
|
|
positive integer which is the number of items remaining to be sent in that
|
|
direction.
|
|
|
|
|
|
``error`` Response
|
|
------------------
|
|
|
|
This response reports an item stack that could not be routed properly. In
|
|
addition to the ``reponse`` key, the message contains ``name`` string and
|
|
``count`` integer keys describing the item stack as well as a ``reason`` string
|
|
key which is one of the following values:
|
|
|
|
``unknown``
|
|
This reason is returned if there are no routing table entries for the item
|
|
type.
|
|
|
|
``toomany``
|
|
This reason is returned if the item stack is larger than the sum of all the
|
|
routing table entries for the item type.
|
|
|
|
``unsplittable``
|
|
This reason is returned if the item stack is within the sum of all routing
|
|
table entries for the item type but larger than the sum of all routing
|
|
table entries for any single colour.
|
|
|
|
In all cases the entire item stack is sent to the unroutable destination.
|