Project Molecule

Project Statement

Project Molecule is a multi-node shared application environment for smart home systems.


The creation of Project Molecule was motivated by frustration over incompatible smart devices on the market. It is intended to be used by 3rd party developers and enthusiasts to link such devices and create a connected home. The project forms a backbone for communication between different devices and handles concerns such as networking, availability, and security.


Project Molecule provides a runtime binary for the system and a common API with documentation for 3rd party app developers. Application creation and configuration tools will be provided to setup new projects and configure our system. An operation manual (Appendix I) is also provided to guide the user through setting up their system and creating an example application. All source code will be provided under the MIT license.


The System is comprised of several nodes called Atoms. Atoms manage all communication in the System and enforce permissions. Atoms also manage and run 3rd party Applications. These Applications run in separate processes and can communicate by sending Messages through the System using a provided API.


Communication uses a Request Response architecture meaning that a Sendor will receive a response Message for each request Message sent. Messages contain routing and protocol data, a sized data payload, and an optional data stream. The optional data stream can be used to send large files or other types of data.

Actions & Payload

Messages implement User or System defined protocols called Actions. The Action type is stored in each Message and allows an Application The type of an Action is part of the header in a Message stored as a String in the Message to reason about the data that will be included in the payload and data streams. For example, when an Application receives a "FILE" ACTION, the message payload of a request will be the following enum:

pub enum FileAction {
    LIST(String),   //List all files in the directory name stored in the contained string
    GET(String),    //Get the file with the name stored in the contained string

The response payload will be dependent on the reqest. i.e:

  • On a List request, the Response Message will return a Vector of Strings representing the file name in a given directory.
  • On a Get request, the Response Message will contain the status of the request and a Stream containing the file data.


Message routing information is only processed on a request. This processing sets up a path for the data to return. Once a request has been received, the response follows this path back to the requestor. If an error occurs, the requesting Application is notified of the failure.

An Atom routes a request by analyzing the following Message parameters:

  1. The Action protocol
  2. An Application identifier filter
  3. An Atom identifier filter

The Identifier filter is one of the following:

Any  - Resolves to one identifier
All  - Resolves to all identifiers
One  - Explicit identifier
Some - Explicit group of identifiers

Here are several examples of how a message would be for the given parameters:

Action Atom App Description
T ALL ALL Broadcasts message to all applications on all atoms which can receive Action T
T ANY ONE(id) Routes a Message to an unspecified instance of the Application
T ALL ONE(id) Routes a Message to all instances of the Application
T ANY SOME(ids) Routes a Message to an unspecified instance of each Application


Applications are 3rd Party Binaries that use our Messaging API and are managed by an Atom. They have a manifest file which specifies:

  • A globally unique identifier
  • A unique human readable name
  • Supported Actions


A developer must declare the Actions an Application can send, receive, or broadcast in order for the Atom to route Messages and enforce permissions. If no Actions are specified, the Application will be effectively cut off from the System.


Applications allow the system to be extensible and connect many different devices. To connect a Smart Thermostat, for example, an Application could implement a "THERMOSTAT" Action which wraps calls to a 3rd party API.