github.com/binkynet/BinkyNet@v1.12.1-0.20240421190447-da4e34c20be0/doc.go (about)

     1  // Copyright 2018 Ewout Prangsma
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  //
    15  // Author Ewout Prangsma
    16  //
    17  
    18  // Package BinkyNet contains a specification for a network architecture used to control model trains.
    19  //
    20  // BinkyNet
    21  //
    22  // The goals of this network architecture are:
    23  //
    24  //   - Knowledge of network layout & users is centralized.
    25  //   - Highly reliable.
    26  //   - Faster than existing train networks such a LocoNet.
    27  //   - Easy to diagnose.
    28  //
    29  // Introduction
    30  //
    31  // BinkyNet consists of 3 major types of entities:
    32  //
    33  // - The network master. This is a centralized unit that has all the knowledge of
    34  // the layout & users of the network. Practically speaking this is one (or more) computers
    35  // that control the operations of everything on the track (trains, switches, lighting...).
    36  //
    37  // - The local worker. This is a unit that is positioned on a specific part of the track (typically 1 per module)
    38  // and has the "brains" to control local slaves.
    39  // This unit receives high level instructions from a network master and translates that to low level instructions
    40  // for local slaves.
    41  //
    42  // - The local slave. This is a unit with very little intelligence and it typically only capable of performing a single function.
    43  // An example of a local slave is an I/O unit that drivers a number of lights or receives bit values from objects
    44  // on the track.
    45  //
    46  // These 3 entities are organized as a tree, with one or more network masters as root.
    47  //
    48  // Network Technologies and Protocols
    49  //
    50  // BinkyNet uses existing & well proven network technologies whereever possible.
    51  //
    52  // Network master - local worker
    53  //
    54  // The network master(s) and local workers are connected using a standard (100Mb+) wired ethernet, configured
    55  // such that the network master and local workers under its control all share the same subnet.
    56  //
    57  // The network master(s) and local workers exchange information (instructions & data) using the MQTT protocol.
    58  // The MQTT protocol provides various levels of quality of service, used to garantee delivery of messages.
    59  //
    60  // Messages can be initiated by both the network master as well as the local worker, allthough the local worker will
    61  // only initiate messages after an initial setup by the network master.
    62  //
    63  // Local worker - local slave
    64  //
    65  // A local worker is connected to its local slaves using a buffered I2C connection.
    66  // The additional buffering is done to allow for a cable length above 1 meter (up to 10 meter).
    67  //
    68  // The local worker and local slaves exchange information that all specific to the implementation of the local slave.
    69  package BinkyNet