Documentation

Configuration Basics

Learn the fundamentals of configuring MudPi using JSON or YAML configuration files.

Configuration File

MudPi loads everything it needs from a configuration file. This file can be in JSON or YAML format. By default, MudPi looks for a file in the root folder named mudpi.config. You are free to locate this file elsewhere and with a name that you choose. To tell MudPi what config file to load you can use the --config flag:

Terminal

mudpi --config /path/to/your_config.file

Note

MudPi will only load components and extensions found in this configuration file on boot. There should not be empty or null values in the config file — instead, omit the option if it is not used.

Minimal Structure

Here is the barebone structure of the configuration file. Place the core configs under the mudpi key:

mudpi.config.json

{
  "mudpi": {
    "name": "MudPi Testbench",
    "debug": false
  }
}

Currently name and debug are the only required options. MudPi includes an example configuration file named mudpi.config.example in the installation root. Additional examples can be found at mudpi/examples.

General Settings

Option	Type	Required	Description
`name`	String	Yes	Name of the system. Used for labeling and UI display.
`debug`	Boolean	Yes	If enabled, MudPi will output more information during startup and each cycle.
`unit_system`	String	No	Measurement units: `imperial` or `metric`.
`location`	Object	No	Object containing `latitude` and `longitude`.
`events`	Object	No	Event adapter configurations. See [Events Configuration](/docs/configuration-events).

Basic Test Configuration

Try booting with only the core configs to verify all dependencies are installed and MudPi runs successfully:

JSON

{
  "mudpi": {
    "name": "MudPi Testbench",
    "debug": false,
    "unit_system": "imperial",
    "location": {
      "latitude": 22.526,
      "longitude": -19.043
    },
    "events": {
      "redis": {
        "host": "127.0.0.1",
        "port": 6379
      },
      "mqtt": {
        "host": "localhost",
        "username": "admin",
        "password": "admin"
      }
    }
  }
}

Here is the same config in YAML format:

YAML

mudpi:
  name: MudPi Testbench
  debug: false
  unit_system: imperial
  location:
    latitude: 22.526
    longitude: -19.043
  events:
    redis:
      host: 127.0.0.1
      port: 6379
    mqtt:
      host: localhost
      username: admin
      password: admin

Troubleshooting

Warning

If your configuration file fails to load, check your value types carefully — "10" is not the same as 10. Ensure there are no empty settings values; options should be removed rather than left empty or null. Verify all quotes, colons, commas, brackets, and capitalization.

Previous ← Configuration Next Sensor Configuration →