Garage Door Opener – Storing the configuration

Up to this point, all of the settings have just been stored in the source code. This will make changing these setting pretty difficult, so I’ll need some way of setting, reading and storing them.

Being a web developer, the first thing I thought of was JSON. There is an Arduino JSON library, and it’s supposedly pretty efficient. Memory is still pretty tight though, and there is some parsing involved, so I started looking at something a little more lo-fi.

The easiest way to go about this would be to create a class with members that match the required settings, but I wanted to make something a bit more re-usable. I knocked up a quick class that allows me to define the layout dynamically.

Config.h

#ifndef Config_h
#define Config_h

#define config_result           uint8_t
#define E_CONFIG_OK             0
#define E_CONFIG_FS_ACCESS      1
#define E_CONFIG_FILE_NOT_FOUND 2
#define E_CONFIG_FILE_OPEN      3
#define E_CONFIG_PARSE_ERROR    4
#define E_CONFIG_MAX            5

#define CONFIG_MAX_OPTIONS      15

#include <EEPROM.h>
#include <FS.h>

class ConfigOption {
  public:
    ConfigOption(const char *key, const char *value, int maxLength);
    const char *getKey();
    const char *getValue();
    int getLength();
    void setValue(const char *value);

  private:
    const char *_key;
    char *_value;
    int _maxLength;
};

class Config {
  public:
    Config();
    config_result addKey(const char *key, int maxLength);
    config_result addKey(const char *key, const char *value, int maxLength);
    config_result read();
    config_result write();

    ConfigOption *get(const char *key);
    bool *set(const char *key, const char *value);
  private:
    int _optionCount;
    ConfigOption *_options[CONFIG_MAX_OPTIONS];
    void reset();
};

#endif

Config.cpp

#include "Config.h"

#define CONFIG_FILE_PATH "/config.dat"

ConfigOption::ConfigOption(const char *key, const char *value, int maxLength) {
  _key = key;
  _maxLength = maxLength;
  setValue(value);
}

const char *ConfigOption::getKey() {
  return _key;
}

const char *ConfigOption::getValue() {
  return _value;
}

int ConfigOption::getLength() {
  return _maxLength;
}

void ConfigOption::setValue(const char *value) {
  _value = (char *)malloc(sizeof(char) * (_maxLength + 1));

  // NULL out the string, including a terminator
  for(int i = 0; i < _maxLength + 1; i++) {
    _value[i] = '&#92;&#48;';
  }

  if(value != NULL) {
    strncpy(_value, value, _maxLength);
  }
}

Config::Config() {
  _optionCount = 0;
};

config_result Config::addKey(const char *key, int maxLength) {
  return addKey(key, NULL, maxLength);
}

config_result Config::addKey(const char *key, const char *value, int maxLength) {
  if(_optionCount == CONFIG_MAX_OPTIONS) {
    return E_CONFIG_MAX;
  }
  _options[_optionCount] = new ConfigOption(key, value, maxLength);
  _optionCount += 1;

  return E_CONFIG_OK;
}

config_result Config::read() {
  if (SPIFFS.begin()) {
    if (SPIFFS.exists(CONFIG_FILE_PATH)) {
      File configFile = SPIFFS.open(CONFIG_FILE_PATH, "r");

      if (configFile) {
        int i = 0;
        int offset = 0;
        int length = 0;

        for(i = 0; i < _optionCount; i++) {
          length += _options[i]->getLength();
        }

        if(length != configFile.size()) {
          return E_CONFIG_PARSE_ERROR;
        }

        uint8_t *content = (uint8_t *)malloc(sizeof(uint8_t) * length);
        configFile.read(content, length);

        for(i = 0; i < _optionCount; i++) {
          // Because we know the right number of bytes gets copied,
          // and it gets null terminated,
          // we can just pass in an offset pointer to save a temporary variable
          _options[i]->setValue((const char *)(content + offset));
          offset += _options[i]->getLength();
        }

        configFile.close();
        free(content);

        return E_CONFIG_OK;
      } else {
        configFile.close();
        return E_CONFIG_FILE_OPEN;
      }
    } else {
      return E_CONFIG_FILE_NOT_FOUND;
    }
  } else {
    return E_CONFIG_FS_ACCESS;
  }
}

config_result Config::write() {
  if (SPIFFS.begin()) {
    int i = 0;
    int offset = 0;
    int length = 0;

    for(i = 0; i < _optionCount; i++) {
      length += _options[i]->getLength();
    }

    File configFile = SPIFFS.open(CONFIG_FILE_PATH, "w+");
    if(configFile) {
      uint8_t *content = (uint8_t *)malloc(sizeof(uint8_t) * length);
      for(i = 0; i < _optionCount; i++) {
        memcpy(content + offset, _options[i]->getValue(), _options[i]->getLength());
        offset += _options[i]->getLength();
      }

      configFile.write(content, length);
      configFile.close();

      free(content);
      return E_CONFIG_OK;
    } else {
      return E_CONFIG_FILE_OPEN;
    }
  }

  return E_CONFIG_FS_ACCESS;
}

/*
 * Returns the config option that maps to the supplied key.
 * Returns NULL if not found
 */
ConfigOption *Config::get(const char *key) {
  for(int i = 0; i < _optionCount; i++) {
    if(strcmp(_options[i]->getKey(), key) == 0) {
      return _options[i];
    }
  }

  return NULL;
}

It consists of two classes: ConfigOption and Config. Config has an array (up to CONFIG_MAX_OPTIONS) of ConfigOptions.

The addKey method adds a ConfigOption to the Config Option. It takes a maximum length, so that we can pre-allocate memory for each string. This makes each configuration length a known quantity, reducing the change of buffer overflows.

There is also a read and write method that reads and writes a blob of data to the SPIFFS flash area. The file format is very simple: a set of concatenated strings of a fixed length – because the class knows the length of each string, it knows exactly where to read each option from. This does make removing or changing the length of an option difficult, though.

Setup is fairly easy:

Config config;

void configSetup() {
  config.addKey("ssid", "", 32);
  config.addKey("passkey", "", 32);
  config.addKey("encryption", "0", 1);

  config.addKey("mqttDeviceName", "garage", 32);

  config.addKey("mqttServer", "", 128);
  config.addKey("mqttPort", "1883", 5);

  config.addKey("mqttAuthMode", "0", 1);
  config.addKey("mqttTLS", TLS_NO, 1);

  config.addKey("mqttUsername", "", 32);
  config.addKey("mqttPassword", "", 32);

  config.addKey("mqttFingerprint", "", 64);

  config.addKey("syslog", "0", 1);
  config.addKey("syslogHost", "", 128);
  config.addKey("syslogPort", "514", 5);
  config.addKey("syslogLevel", "6", 1);

  switch(config.read()) {
    case E_CONFIG_OK:
      Serial.println("Config read");
      return;
    case E_CONFIG_FS_ACCESS:
      Serial.println("E_CONFIG_FS_ACCESS: Couldn't access file system");
      return;
    case E_CONFIG_FILE_NOT_FOUND:
      Serial.println("E_CONFIG_FILE_NOT_FOUND: File not found");
      return;
    case E_CONFIG_FILE_OPEN:
      Serial.println("E_CONFIG_FILE_OPEN: Couldn't open file");
      return;
    case E_CONFIG_PARSE_ERROR:
      Serial.println("E_CONFIG_PARSE_ERROR: File was not parsable");
      return;
  }
}

This sets up each of the keys with a name, a default value and a max length. It then reads in the configuration file from the flash.

To read the options, you can do this:

int authMode = atoi(config.get("mqttAuthMode")->getValue());
int tls = atoi(config.get("mqttTLS")->getValue());

Note: every config comes back as a string, so they need to be cast if required.

The beauty of using a config file read from flash means I can build the configuration externally and upload it, which means I don’t have to have a configuration system built yet – and it means I know exactly what config options I’ll need when I finally build the configuration system.

I created a super small program in C++ that compiles with G++. The header file is exactly the same as one above. The CPP file looks like this:

#include <string.h>
#include <stdlib.h>
#include <stdio.h>

#include "config.h"

ConfigOption::ConfigOption(const char *key, const char *value, int maxLength) {
  _key = key;
  _maxLength = maxLength;
  setValue(value);
}

const char *ConfigOption::getKey() {
  return _key;
}

char *ConfigOption::getValue() {
  return _value;
}

int ConfigOption::getLength() {
  return _maxLength;
}

void ConfigOption::setValue(const char *value) {
  if(_value) {
    free(_value);
  }

  _value = (char *)malloc(sizeof(char) * (_maxLength + 1));

  // NULL out the string, including a terminator
  for(int i = 0; i < _maxLength + 1; i++) {
    _value[i] = '&#92;&#48;';
  }

  if(value != NULL) {
    strncpy(_value, value, _maxLength);
  }
}

Config::Config() {
  _optionCount = 0;
};

config_result Config::addKey(const char *key, int maxLength) {
  return addKey(key, NULL, maxLength);
}

config_result Config::addKey(const char *key, const char *value, int maxLength) {
  if(_optionCount == CONFIG_MAX_OPTIONS) {
    return E_CONFIG_MAX;
  }
  _options[_optionCount] = new ConfigOption(key, value, maxLength);
  _optionCount += 1;

  return E_CONFIG_OK;
}

config_result Config::read() {
  int i;
  int offset = 0;
	int length = 0;

  for(i = 0; i < _optionCount; i++) {
    length += _options[i]->getLength();
  }

  char *content = (char *)malloc(sizeof(char) * length);

  FILE *f = fopen("config.dat", "r");
  fread(content, sizeof(char), length, f);
  fclose(f);

  for(i = 0; i < _optionCount; i++) {
    // Because we know the right number of bytes gets copied,
    // and it gets null terminated,
    // we can just pass in an offset pointer to save a temporary variable
    _options[i]->setValue(content + offset);
    offset += _options[i]->getLength();
  }

  free(content);
}

config_result Config::write() {
	int i;
  int offset = 0;
	int length = 0;

  for(i = 0; i < _optionCount; i++) {
    length += _options[i]->getLength();
  }

  char *content = (char *)malloc(sizeof(char) * length);
  for(i = 0; i < _optionCount; i++) {
    printf("%s\n", _options[i]->getKey());
    memcpy(content + offset, _options[i]->getValue(), _options[i]->getLength());
    offset += _options[i]->getLength();
  }

  FILE *f = fopen("config.dat", "w");
  fwrite(content, sizeof(char), length, f);
  fclose(f);
  printf("Length: %d\n", length);
}

ConfigOption *Config::get(const char *key) {
  for(int i = 0; i < _optionCount; i++) {
    if(strcmp(key, _options[i]->getKey()) == 0) {
      return _options[i];
    }
  }
  return NULL;
}

bool Config::set(const char *key, const char *value) {
  for(int i = 0; i < _optionCount; i++) {
    if(strcmp(key, _options[i]->getKey()) == 0) {
      _options[i]->setValue(value);
      return true;
    }
  }
  return false;
}

int main(int argc, char **argv) {
  Config config;

  config.addKey("ssid", "", 32);
  config.addKey("passkey", "", 32);
  config.addKey("encryption", "0", 1);

  config.addKey("mqttDeviceName", "garage", 32);

  config.addKey("mqttServer", "", 128);
  config.addKey("mqttPort", "1883", 5);

  config.addKey("mqttAuthMode", "0", 1);
  config.addKey("mqttTLS", "0", 1);

  config.addKey("mqttUsername", "", 32);
  config.addKey("mqttPassword", "", 32);

  config.addKey("mqttFingerprint", "", 64);

  config.addKey("syslog", "0", 1);
  config.addKey("syslogHost", "", 128);
  config.addKey("syslogPort", "514", 5);
  config.addKey("syslogLevel", "6", 1);

  config.set("ssid", "[ssid]");
  config.set("passkey", "[passkey]");
  config.set("encryption", "2");
  config.set("mqttServer", "[mqtt server name]");
  config.set("mqttPort", "8883");
  config.set("mqttAuthMode", "2");
  config.set("mqttTLS", "1");
  config.set("mqttFingerprint", "[fingerprint]");

  config.set("syslog", "1");
  config.set("syslogHost", "[log server name]");
  config.set("syslogPort", "514");
  config.set("syslogLevel", "7");

  config.write();
  return 0;
}

Some sensitive settings have been redacted.

Compile it with:

g++ config.cpp -o config

And then run it. It’ll generate a config.dat file, that I just copy to the data directory of the Arduino project. I then upload it using the ESP8266 Sketch Upload tool.

I’m not 100% sold on this, I wonder whether I should just create a class with static members, rather than dynamically building it. Ironically, it might be better to build the strings dynamically so only the memory required is used (up to a maximum length to avoid those scary buffer overflows).

If I start hitting memory limits, I’ll revisit.