> ## Documentation Index
> Fetch the complete documentation index at: https://docs.directenergypartners.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

The configuration file is essential for the proper functioning of the controller, as it includes important settings related to its communication interfaces, such as MQTT, CAN, Telegram, and NATS. The configuration file supports the following entries:

## Required Entries

These entries must be configured for each controller:

* **plcnext**
* **mqtt**
* **nats**

## Optional Entries

These entries can be added to enable additional functionality. If included, their parameters must be configured correctly:

* **can** - configures CAN bus interfaces
* **telegram** - enables Telegram notifications and alerts

Below, we will provide detailed information on each entry, including the required parameters and any optional ones. The configuration file can be found in the `/etc` folder of the `ppl-base` repository and is listed as `config.json`.

## plcnext

### Required Parameters

<ParamField path="ipAddress" type="string" required>
  This is the IP address of the controller. It should always be configured to the controller’s current IP address, as it is used to create sockets.

  **Example:** `192.168.1.10`
</ParamField>

### Optional Parameters

Though these parameters are not required for the controller to operate, it is good practice to include them in the configuration file to avoid losing track of login credentials.

<ParamField path="username" type="string">
  The username for logging into the WBM of the controller or a shell session. This should be set to `admin`.

  **Example:** `admin`
</ParamField>

<ParamField path="password" type="string">
  The password for logging into the WBM of the controller or a shell session.

  **Example:** `password`
</ParamField>

## mqtt

### Required Parameters

<ParamField path="broker" type="object" required>
  This entry contains all relevant information for the MQTT broker.

  <Expandable title="properties">
    <ParamField path="ipAddress" type="string" required>
      This is the IP address of the broker. The broker is hosted on the Power Platform controller itself, so this should always be the controller’s IP address.

      **Example:** `192.168.1.10`
    </ParamField>

    <ParamField path="port" type="number">
      The port number of the MQTT broker. If not specified, it defaults to `1883`.

      **Default:** `1883`
    </ParamField>
  </Expandable>

  **Example:**

  ```json icon="code" theme={null}
  {
    "broker": {
      "ipAddress": "192.168.1.10",
      "port": 1883
    }
  }
  ```
</ParamField>

## nats

### Required Parameters

The required parameters are used to set up a local NATS server on the controller. This NATS server is used to integrate with custom applications developed by the customer.

<ParamField path="local" type="object" required>
  The required parameters are used to set up a local NATS server on the controller. This NATS server is used to integrate with custom applications developed by the customer.

  <Expandable title="properties">
    <ParamField path="username" type="string" required>
      The username for connecting to the local NATS server.

      **Example:** `client`
    </ParamField>

    <ParamField path="password" type="string" required>
      The password for connecting to the local NATS server.

      **Example:** `password`
    </ParamField>
  </Expandable>

  **Example:**

  ```json icon="code" theme={null}
  {
    "local": {
      "username": "client",
      "password": "password"
    }
  }
  ```
</ParamField>

### Optional Parameters

The optional parameters are used for setting up a NATS connection to the cloud, which hosts a database for storing data. By providing these parameters, the controller can periodically push data to the cloud.

<ParamField path="cloud" type="object">
  The optional parameters are used for setting up a NATS connection to the cloud, which hosts a database for storing data. By providing these parameters, the controller can periodically push data to the cloud.

  <Expandable title="properties">
    <ParamField path="username" type="string">
      The username for connecting to the cloud NATS server.

      **Example:** `client`
    </ParamField>

    <ParamField path="password" type="string">
      The password for connecting to the cloud NATS server.

      **Example:** `password`
    </ParamField>

    <ParamField path="ipAddress" type="string">
      The IP address of the cloud NATS server.

      **Example:** `192.168.1.5`
    </ParamField>

    <ParamField path="bucket" type="string">
      The bucket name for storing data.

      **Example:** `my-bucket`
    </ParamField>
  </Expandable>

  **Example:**

  ```json icon="code" theme={null}
  {
    "cloud": {
      "username": "client",
      "password": "password",
      "ipAddress": "192.168.1.5",
      "bucket": "my-bucket"
    }
  }
  ```
</ParamField>

## can <span style={{color: 'gray', fontSize: '0.8em'}}>(optional)</span>

The `can` entry is an optional array that configures the CAN bus interfaces on the controller. Each entry in the array represents a CAN bus interface. If this entry is included, the following parameters are required.

### Required Parameters

<ParamField path="can[]" type="array" required>
  An array of CAN bus interface configurations.

  <Expandable title="properties">
    <ParamField path="bitRate" type="number" required>
      The bit rate of the CAN bus interface. Must be one of the following values: `10000`, `20000`, `50000`, `125000`, `250000`, `500000`, `800000`, `1000000`.

      **Example:** `500000`
    </ParamField>

    <ParamField path="slotNumber" type="number" required>
      The slot number of the CAN bus interface/module in the bus configuration. Must be a value between 1 and 64 (inclusive).

      **Example:** `1`
    </ParamField>
  </Expandable>

  **Example:**

  ```json icon="code" theme={null}
  [
    {
      "bitRate": 500000,
      "slotNumber": 1
    },
    {
      "bitRate": 125000,
      "slotNumber": 5
    }
  ]
  ```
</ParamField>

## telegram <span style={{color: 'gray', fontSize: '0.8em'}}>(optional)</span>

The `telegram` entry is optional and can be used to enable notifications and alerts. These include livebit messages every 24 hours and alerts for critical device failures in the system. If the customer does not wish to receive updates via Telegram, they simply need to omit this entry from the config file. If this entry is included, the following parameters are required.

### Required Parameters

<ParamField path="chatID" type="string" required>
  Represents the unique chat ID of the Telegram channel. Each Telegram channel has its own unique ID.

  **Example:** `123456789`
</ParamField>

<ParamField path="botToken" type="string" required>
  A token consisting of letters and numbers, required for authorizing the bot and sending requests to the Bot API. The Bot API is already added to the Telegram channel.

  **Example:** `123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ`
</ParamField>

## File Validator

Use the File Validator to verify that your `config.json` is correct, contains no errors, and includes all required parameters so the PPL controller can start up properly.

<Card title="Open File Validator" icon="check" href="https://validator.directenergypartners.com" horizontal>
  Validate your configuration files before uploading them to the controller.
</Card>