Skip to content

Configuration

Jump to bottom
akerr501 edited this page Jun 2, 2020 · 5 revisions

Table of Contents

Overview

Your Loom device's settings and behavior is largely defined by the configuration you specify. More behavior and program flow is specified in the .ino file's loop, but the configuration is used to determine what Loom Modules you have access to.

Including Configuration

Configurations are in the form of JSON (a string version of a JavaScript object). The configuration can be provided to the device in a few different ways:

  • #include the string directly in the .ino file (see Loom examples > Configuration for examples of different ways of doing this)
  • Store the configuration on an SD card, then use code to specify what configuration to load
    • You can load a different configuration when running to switch the settings / enabled features
  • (feature in progress) Send the device a configuration over the internet using Spool

You can use the #include method as a fallback in the event that one of the other methods fails.

Configuration Structure

The configurations have two parts, general settings and list of modules to create.

General Settings

The general settings are contained in a an object associated with the key general. The object contains key value pairs that specify settings that apply to your device as a whole, and are not module (individual hardware / feature representation) specific. Such settings include the device's name, instance number, and the interval between loop iterations.

Example:

'general':
{
	'name':'LoomDevice',
	'instance':42,
	'interval':3000
}

Modules

Each Loom Module can be instantiated (created) by providing the any object listing the module's settings in the configuration. The modules to use are specified in the array associated with the key components. For each module, you need to specify the name and parameters, the latter of which can be listed out completely, or in many cases, as default.

Example

'components':
[
  {
    'name':'Analog',
    'params':'default'
  },
  {
    'name':'Relay',
    'params':[10]
  }
  {
    'name':'SD',
    'params':[
      true,
      1000,
      10,
      'savefile.csv'
    ]
  },
  {
    'name':'PCF8523',
    'params':[11,true]	
  },
  {
    'name':'WiFi',
    'params':[
      'some_network',
      'the_password'
    ]
  }
]

The settings for each module correspond to the parameters of the module's constructor. Once the Loom Configurator is complete, you will not have to look at the code or documentation for these settings, as the web app will find and provide the possible values for you.

Where do I find this information?

The settings and possible values they can take are specified in the code, and generated in the documentation. Once you've gone to the Doxygen, you can click on the classes tab on the top of the website

1

Once you’re looking at the class list, you should be able to locate the name of your specific sensor or module that you want to use. After clicking on your sensor of desire, you can scroll down on the Doxygen page to the constructor documentation for the sensor (this may look different depending on what you’re working with). Down below is an example from the SD documentation. Once you’ve located the parameter information, you are ready to work on your config.h file.

2

You can follow a guide on how to setup a config.h file on the Configuration Setup page located here

What if the sensor is not in Doxygen?

Posting an Issue on the Loom page is going to be your best solution to get this information. We will try to help any short term problems quickly and start making that documentation for that sensor or module available.

How the Configuration is Processed

The LoomManager uses the ArduinoJson library to deserialize the configuration JSON into a representation of a JavaScript object. The manager will apply any of the provided general settings to itself, using default values for those not provided. The manager will then interate over the modules in the components array, sending each module to the LoomFactory, which will try to instantiate the corresponding LoomModule by matching the name to one of the available modules. If found, the factory will call that LoomModule's constructor with the params array, or if not parameters if the module has default values for all parameters and the configuration specifies default. The factory then returns a pointer to the created module (or nullptr if the module could not be created) to the manager, with adds it to its vector of module pointers.

Invalid Syntax: If your configuration is not in the correct format, it cannot be parsed. This could be something as simple missing a comma.

Sorting

Once all of the modules have been created, the manager sorts the vector of LoomModule pointers based on their type.

Second Stage Construction

Once the modules are sorted the manager calls the second stage constructor on each of them. This "constructor" is used to finish any setup that the module might need to execute but cannot until another module has been created. This process ensures that you can specify the modules in any order in your configuration without needing to worry about which modules depend on another.

Replacing Previous Configuration

Once your devices is running, its configuration can be altered. If you only want to modify the settings of existing modules at runtime, then see the documentation for available methods to do so. You can, however, also load an entirely different configuration. By using one of the methods parse_config, parse_config_SD, parse_config_json the manager will remove all current modules and resetup based on the new configuration.

Loom Factory

Factory is used by LoomManager when parsing Json to match module names to their associated constructors, and calling with parameters from the Json. However, Loom has grown to the point that the entirety of the library's code does not fit into the program storage of the Adafruit Feather M0s. To address this, the factory's lookup table was fragmented into togglable sections that are selected at compile time, giving you control over what features are enabled and thus how much flash storage Loom takes up. Template parameters are used to select whether certain blocks of modules are included in the lookup table.

To build the factory according to some settings, you make a global LoomFactory instance in your .ino file and provide a pointer to it to the Loom manager:

#include <Loom.h>

// Set enabled modules
LoomFactory<
	Enable::Internet::All,
	Enable::Sensors::Enabled,
	Enable::Radios::Disabled,
	Enable::Actuators::Disabled,
	Enable::Max::Disabled
> ModuleFactory{};

LoomManager Loom{ &ModuleFactory };

This specifies what modules the factory can create, not that it will necessarily create all of these in setup. If you specify a module in the configuration that Loom supports but is not in the lookup table in the way you specified the factory, it will not be created. Thus, the settings you specify the factory to have should reflect what you want to have modules for, as this can only be set before compiling and cannot be changed at runtime. Even if you load a different configuration in the middle of operation, it will still be constrained to the modules the factory was compiled to have access to. Disabled features that you do not need to save space.

Factory Construction Options:

Option Possible Settings
Internet All, WiFi, Ethernet, LTE, Disabled
Sensors Enabled, Disabled
Radios Enabled, Disabled
Actuators Enabled, Disabled
Max Enabled, Disabled

Loom Wiki Home • Code • Documentation

Clone this wiki locally