Module search 

Train Search protocol: find (or allocate) a train node by DCC address by emitting Identify Producer for a specially formed event ID. Matching train nodes answer with Producer Identified for the same event.

The Train Search Standard reserves the event range 09.00.99.FF.xx.xx.xx.xx. The low 32 bits encode the query:

 63            32 31                         8 7        0
+----------------+----------------------------+----------+
|  0x090099FF    | 6 nibbles: query digits,   |  flags   |
|  (PREFIX)      | right-aligned, unused = F  |          |
+----------------+----------------------------+----------+

 e.g. DCC 1234:  09.00.99.FF . FF.12.34 . 6C

 flags: 0x80 ALLOCATE      create the train if none matches
        0x40 EXACT         exact match only
        0x20 ADDRESS_ONLY  match the address, not the name
        0x08 DCC           DCC protocol
        0x04 DCC_LONG_ADDRESS
        0x03 speed steps   0 default, 1 = 14, 2 = 28, 3 = 128

A throttle sends Message::IdentifyProducer with the search event. Every train node that matches (the command station allocates a new virtual train node first if ALLOCATE is set) answers with Producer Identified for the same event ID; the source alias of that reply is the train to control.

use rolcb::traction::search;

let e = search::dcc_event(3, false, 0);
assert_eq!(e.0, 0x0900_99FF_FFFF_F368); // digits "3", EXACT|ADDRESS_ONLY|DCC
let e = search::dcc_event(1234, false, search::ALLOCATE);
assert_eq!(e.0, 0x0900_99FF_FF12_34EC); // >127 forces the long-address flag
assert!(search::is_search_event(e));
assert_eq!(search::decode(e), Some((1234, 0xEC)));

Constants

ADDRESS_ONLY

Match only against the address, not the train name.

ALLOCATE

Create the train if no match exists (command station allocates it).

DCC

DCC protocol.

DCC_LONG_ADDRESS

Force a DCC long (extended) address.

EXACT

Only exact matches.

PREFIX

Upper 32 bits of every train search event.

SPEED_STEPS_MASK

Speed step bits (with DCC): 0 = default, 1 = 14, 2 = 28, 3 = 128.

Functions

dcc_event

Build the search event for a DCC address. Addresses above 127 are always long; long forces a long address for low numbers.

decode

Decode a search event into (number, flags). Non-digit nibbles are skipped.

is_search_event

True if e lies in the train search event range (PREFIX).

query_event

Build a search event from a numeric query (up to 6 decimal digits).