Vendors

Every machine type is identified by a vendor_id and a machine_id (MachineIdentification). The vendor id says who defined the machine type. The machine id is chosen by that vendor. qitech_framework_core/vendors.toml is the registry of vendor ids.

Together, the two ids make a machine type globally unique. The pair appears in every schema, in every message about a machine on the wire, in the vendor:machine:serial instance identity, and in the machine identity stored in EtherCAT device EEPROMs. Two vendors must therefore never share an id.

The file

qitech = { id = 1, name = "QiTech GmbH" }

Each line is one vendor:

Part	Meaning	Rules
key (qitech)	short identifier	becomes a Rust constant in UPPERCASE (vendors::QITECH), so it must be a valid identifier
id	vendor id, u16	unique, and never reassigned
name	display name	unique; used for lookups by name

Unknown fields are rejected (deny_unknown_fields).

Using vendor ids

In a machine's schema:

identification:
  name: laser_v1
  vendor_id: 1        # QiTech GmbH
  machine_id: 6

In Rust, qitech_framework::vendors (re-exported from qitech_framework_core::vendors) offers:

use qitech_framework::vendors;

vendors::QITECH.id                 // 1
vendors::QITECH.name               // "QiTech GmbH"

vendors::get_name(1)               // Some("QiTech GmbH")  (const fn)
vendors::get_id("QiTech GmbH")     // Some(1)
vendors::contains_id(1)            // true             (const fn)
vendors::contains_name("QiTech GmbH")

A machine can use the constant to state its identity in code:

pub const IDENTIFICATION: MachineIdentification = MachineIdentification {
    vendor_id: vendors::QITECH.id,
    machine_id: 6,
};

Usually you don't need this, because #[derive(Machine)] already provides IDENTIFICATION from the schema (see Creating a Machine).

What gets generated

qitech_framework_core/build.rs reads the file on every build and writes vendors.rs into OUT_DIR. It's included as a private generated module inside qitech_framework_core::vendors:

mod generated {
    pub struct Entry { pub id: u16, pub name: &'static str }

    pub const QITECH: Entry = Entry { id: 1, name: "QiTech GmbH" };

    pub const fn get_name(id: u16) -> Option<&'static str> { match id { 1 => Some("QiTech GmbH"), _ => None } }
    pub fn get_id(name: &str) -> Option<u16> { match name { "QiTech GmbH" => Some(1), _ => None } }
}

vendors re-exports Entry, get_name and get_id, and builds contains_id and contains_name on top of them.

Only QITECH is re-exported as a constant (pub const QITECH: Entry = generated::QITECH; in qitech_framework_core/src/lib.rs). A newly added vendor's constant exists in generated, but it isn't reachable from outside until you add a matching re-export line.

Adding a vendor

1. Choose the next free id. Never reuse an id, even from a vendor that no longer exists: machines in the field, EEPROMs and stored data still refer to it.

2. Add a line to vendors.toml:

   qitech = { id = 1, name = "QiTech GmbH" }
   acme = { id = 2, name = "ACME Machines" }

3. Re-export the constant in qitech_framework_core/src/lib.rs:

   pub const ACME: Entry = generated::ACME;

4. Build. Machines of the new vendor can now use vendor_id: 2 and vendors::ACME.id.

For vendors outside QiTech: the file lives in the framework, so a new vendor needs a change to the framework repository. Ask for an id to be assigned there, rather than choosing one yourself in a fork. Once the id is assigned, you choose your own machine_ids.