This page is retained for historical reference and may not reflect the current MOSH/IMC/MTRP architecture. See [[guide:architecture_map]] for the current model. ====== MOSH Project Overview ====== MOSH is a decentralized, protocol-level framework for IoT devices. Unlike other protocols and their networks, MOSH requires **no internet** and **no fixed infrastructure**. MOSH is specifically developed for use-cases where internet connectivity isn't possible, is unreliable, or unwanted. This allows MOSH to be a fully-featured, modern protocol with many of the same features and functions of other protocols that rely heavily on an internet connection. Additionally, MOSH requires no additional hardware, or hub, to enable automations. Rather, MOSH uses a concept called a Virtual Wire™ to connect elements with one another. A MOSH network consists of nodes, with each node containing one or more elements (sensors, LEDs, etc). Elements then connect to other elements via one (or more) virtual wires. Virtual wires are, at their core, communication paths that allow an element to share information with other elements. Information is then processed by a MOSH Condition, which, simply put, is a conditionalized statement that tells the element what to do. MOSH Conditions are a rough equivalent to automations in other smart home networks. It's also possible to have multiple MOSH networks, each with a different transport type. In order to "bridge" these networks MOSH implements a feature called a MOSH Coordinator. MOSH Coordinators, as their name implies, coordinate communication between elements on different networks, and can also hosts elements on their own. ====== MOSH Nodes: ====== MOSH is structured such that no hardware, other than individual peripherals, are necessary for a network to function -- a hub or wireless router isn't necessarily required. This means that any network-local node, can configure any other network-local node, from a feature-rich command line interface (CLI). However, the MOSH development project also provides a MOSH Coordinator Node (MCN), to make setup and configuration as user-friendly as possible. === Bridge: === * A node that relays messages between different transports. * A [[mosh:devices:bridge|bridge]] doesn't necessarily need to contain any elements. They can be stand alone nodes, although they are often paired with elements. === Coordinator: === * The primary logic node that manages pairing, groups, and policy. * Typically a Teensy or Pi with multiple transports. * Tracks node states, and enforces policy. * Optional in fully decentralized setups. === Gateway (optional role): === * A node that interfaces with external systems (e.g., internet, phone app, MQTT). * Can push sensor data to external systems. * May host a web UI or OTA update server * Usually built on a Pi or ESP32 with Wi-Fi ===Peripherals and Nodes:=== * A peripheral (or node) performs a dedicated function (like sensing or controlling), but does not manage the network. * Usually connects via ESP-NOW, Serial, or Wi-Fi. * Includes buttons, sensors, relays, etc. ====== MOSH Protocol: ====== MOSH, strictly speaking, is a messaging protocol. MOSH nodes communicate with one another by exchanging MOSH messages. These messages handle things like: * Node status * Element state * Neighbor information * Local transport policy * Virtual wire updates * Various security related information MOSH messages are sent by transports -- radios or other communications devices registered with MOSH. MOSH's initial development will support Serial, IP, ESP-NOW, and Bluetooth networks, and subsequently be extended to supporting other radios like the nRF24L01, nRF52840, and LoRa. ==== Using the MOSH Protocol Library: ==== The MOSH library is meant to be relatively straight-forward -- allowing a simple configuration for new users, as well as other configuration options for more advanced users, and increasingly complex installations. The basic sketch work-flow is as follows: * Create the MOSH object * Register a transport (ESP-Now, WiFi, nrf24L01, etc) * Register an element (LED, button, rotary encoder, etc) * Register an elements priority call-back (optional) Once compiled, configure the elements (via dedicated Coordinator or CLI): * Add element to Virtual Wire * Configure MOSH Conditions The basic loop structure: * Call mosh.loop() method * Read a MOSH elements properties (optional) * Write a MOSH elements properties (optional)