MyController is an IoT automation controller for home, office or any place.
There is no internet requirement for the MyController. You can run the complete setup on your private environment
MyController is designed to run with a limited resources. It can run on the first generation of the Raspberry PI.

MyController 2.x is completely redesigned. You can not upgrade from MyController 1.x

Technologies Used

Backend
- GoLang
- Nats.io - Message Bus
Supported Databases
- Storage
  - In-Memory - developed and maintained by MyController community
  - MongoDB
- Metric
  - InfluxDB
Frontend - Web Console
- ReactJS
- PatternFly - Web Console
- react-grid-layout - Dashboard
Documentation
- gohugo
- docsy

Architecture Guide

MyController Services and Bundles

MyController has many services and all communicates via Message Bus.
Based on the services and use cases, MyController bundled as follows,

Server
Gateway
Handler

Server Setup

server setup

This package contains MyController Server + Gateway + Handler services
All the services combined and bundled as single binary
As it has all the services in a single binary, It is possible to use embedded Bus, which cannot be accessible outside of the MyController server (Options #1)
If you have plan to use external gateway, or handler you have to go with external bus service (natsio) (Option #2)

Gateway Setup

gateway setup

There is a gateway only bundle
This service can be connected to a MyController server via the external message bus.
You can have many number of gateway services on different hosts

Handler Setup

handler setup

There is a handler only bundle
This service can be connected to a MyController server via the external message bus.
You can have many number of handler services on different hosts

Supported Providers

What next?

Getting Started

1.1 - Architecture

architecture

Message bus

All services rely on centralized message bus. Which leads we can have micro service for each block shown above.
Most of the components based on a plugin approach. Other services can be included easily

Gateway

Gateway is a service that collects data from different networks. Also can do changes on the target network.
Gateway is as plugin component, we can implement gateway for any provider
Supported providers list

Gateway Message Processor

Collects data from a gateway and updates in storage and metrics database
Sends received data as events, will be used in other services (Task, Forward Payload, etc.,)

Forward Payload

Forwards a payload from a Field to another Field
Fields can be on a different gateways

Task Service

User defined tasks will be executed by Task Service
Two types of tasks are available

Event based
- Tasks can listen to specific events.
Execute on an interval
- executes tasks based on the interval defined

If task meets the defined criteria, posts the given parameters to the Handler Service

Scheduler Service

User defined schedules are executed by Scheduler Service
outcome of the schedule execution handover the defined parameters to the Handler Service

Handler Service

Receives requests from Task Service and Scheduler Service
Submits the parameters to a specific handler
new handlers can be implemented easily as it is a plugin component

API and Websocket Service

Exposes set of APIs to consume and operate resources
Websocket notifies the changes on the resources, helps to sync the dashboard realtime
Web UI is client consumes query service APIs
- User can add/modify most of the data here
- Update Gateway details
- Create a dashboard with different widgets
- Add a schedule, task, handler, firmware
- Run a backup, restore
- etc…

Storage Database

Stores all the data other than metrics
- gateways, Node, Source, Fields, Dashboard, Task, Scheduler, Handler, etc.,
storage is a plugin type
Currently there are two type of supported storage plugin
- in-memory
  - Keeps all the configurations on the memory/RAM
  - Dumps into disk with defined intervals
  - On startup loads from the disk
- MongoDB

Metric Database

Stores only the metrics data
Metric is a plugin type
Currently supports InfluxDB

2 - Getting Started

Prerequisites

Installation can be done in two different methods,

Run from the executable binary bundles
Run it as a container

Hardware Requirements

Disk Space: ~100 MiB
Memory(RAM): ~50 MiB

Software Requirements

InfluxDB - used as a metric store
Optional
- Docker or any container orchestration (if you plan to run MyController container image)
- MongoDB - can be used as a configuration store

Dependencies Installation

Migrating MyController from 1.x to MyController 2.0

MyController 2.0 is completely redesigned.
You can not migrate from 1.x to 2.0
However for sometime you can run 1.x and 2.0 simultaneously and migrate your configurations manually
If you are using MySensors serial port to connect your sensors, use 2mqtt to share your sensors network to both 1.x and 2.0

Install MyController Server

What Next?

Hints

2.1 - Hints

if a boolean value is left blank. It is considered as false
if a numerical value is left blank, It is considered as 0

Values on payloads

Payloads sent to a resource will be considered as follows

case in-sensitive
on, true, 1, enable == true
off, false, 0, disable == false

Duration of the time

System time durations follow the GoLand standards as follows…

ns - nanoseconds
us - microseconds
ms - milliseconds
s - seconds
m - minutes
h - hours

Examples:

Input	Description
`0`	0 seconds
`0s`	0 seconds
`10s`	10 seconds
`1m20s`	1 minute and 20 seconds
`1h20m5s`	1 hour 20 minutes and 5 seconds
`-42s`	-42 seconds

Note

Negative numbers are supported.

Labels

TBD

Quick ID

TBD

2.2 - Install Docker

Docker can be installed in different way. Here it is explained to install it on Raspberry PI with Raspbian OS
Follow the steps below to install docker on your Raspberry PI

Note

Assuming that you are running all the commands as a root user.
If you are running from non-root user, you should include sudo in the beginning of the commands.

# copy the installation script
curl -fsSL https://get.docker.com -o get-docker.sh

# execute the script
sh get-docker.sh

# enable the docker daemon
systemctl enable docker.service

# start the docker daemon
systemctl start docker.service

# check the docker daemon is active
systemctl is-active docker.service

Optional steps - If you plan to play docker command on user

# add a non-root user to the docker group
# here the "pi" is a user
usermod -aG docker pi

2.3 - Install InfluxDB

Supported Versions

MyController supports InfluxDB 1.8.x or above

In this guide installation shown on Raspberry Pi with Raspbian Linux OS
If you have different OS, refer the influxdb installation guide
Influxdb can be installed in two different ways

Install InfluxDB on the host system
Install InfluxDB on the docker

Install InfluxDB on the host system

Follow this guide to install InfluxDB directly on your host system

Run the following commands as a root user
Operating System: Raspbian Linux 10 (buster)

# configure influxdb repository
wget -qO- https://repos.influxdata.com/influxdb.key | apt-key add -
echo "deb https://repos.influxdata.com/debian buster stable" | tee /etc/apt/sources.list.d/influxdb.list

# update package details to the local system
apt update

# install influxdb and enable to run at startup
apt install influxdb
systemctl enable influxdb.service

# start influxdb
systemctl start influxdb.service

Optionally you can disable self monitoring metrics to avoid unnecessary CPU and Disk usage.

update the following line on /etc/influxdb/influxdb.conf
```
[monitor]
  store-enabled = false
```
restart the influxdb service
```
systemctl restart influxdb.service
```

(Optional) Create a database for MyController usage in influxDB

If the database user has admin privilege, database will be created automatically by MyController server.

root@rpi-171:~# influx
Connected to http://localhost:8086 version 1.8.5
InfluxDB shell version: 1.8.5
> create database mycontroller
> show databases
name: databases
name
----
mycontroller
> exit

Install InfluxDB on the Docker

Most of the places docker installation of influxdb works well

Warning

In ARM v6, docker version of InfluxDB not started and no issues reported. Tested it on 1.8.4
We can directly install it on the host system by following this guide
To know your machine architecture execute uname -m on the command line

$ uname -m
armv6l

Note

Assuming that you are running all the commands as a root user.
If you are running from non-root user, you should include sudo in the beginning of the commands.

Generate influxdb.conf

Detailed information is on InfluxDB Website

generate influxdb.conf

mkdir -p /opt/apps/influxdb
cd /opt/apps/influxdb

docker run --rm influxdb:1.8.4 influxd config > influxdb.conf

Optional - Steps to disable InfluxDB monitor
- Monitor InfluxDB metrics will be enabled by default. It eats lot of disk space and CPU.
- on the generated influxdb.conf set false to store-enabled, available under monitor
```
[monitor]
  store-enabled = false
```

Install

Variable $PWD

$PWD is a Print Working Directory.

mkdir -p /opt/apps/influxdb/influxdb_data
cd /opt/apps/influxdb

docker run --detach --name mc_influxdb \
    --publish 8086:8086 \
    --volume $PWD/influxdb_data:/var/lib/influxdb \
    --volume $PWD/influxdb.conf:/etc/influxdb/influxdb.conf:ro \
    --env TZ="Asia/Kolkata" \
    --restart unless-stopped \
    influxdb:1.8.4

(Optional) Create a database for MyController usage in influxDB

If the database user has admin privilege, database will be created automatically by MyController server.

enter inside running docker container
execute influx command inside the influx container as follows
create a database by running create database mycontroller
show available databases by running show databases
type exit two time, one exits from influx client shell, second exits from the docker container

$ docker exec -it mc_influxdb /bin/sh

# influx
Connected to http://localhost:8086 version 1.8.4
InfluxDB shell version: 1.8.4
> create database mycontroller
> show databases
name: databases
name
----
mycontroller
> exit
# exit

To see the logs

Prints all available logs
```
docker logs mc_influxdb
```
Prints and tails the logs, to get exit do Ctrl+C
```
docker logs --follow mc_influxdb
```

Stop

docker stop mc_influxdb

Restart

docker restart mc_influxdb

Uninstall

docker stop mc_influxdb
docker rm mc_influxdb

2.4 - Install natsio

Supported Versions

MyController server tested on nats.io 2.2.2

nats.io server can be installed in different way. Here we are focusing to setup it on docker and nats.io 2.2.2 version.

To install natsio on your host system follow this guide

Note

Assuming that you are running all the commands as a root user.
If you are running from non-root user, you should include sudo in the beginning of the commands.

Install

docker run --detach --name mc_natsio \
    --publish 4222:4222 \
    --env TZ="Asia/Kolkata" \
    --restart unless-stopped \
    nats:2.2.2-alpine

To see the logs

Prints all available logs
```
docker logs mc_natsio
```
Prints and tails the logs, to get exit do Ctrl+C
```
docker logs --follow mc_natsio
```

Stop

docker stop mc_natsio

Restart

docker restart mc_natsio

Uninstall

docker stop mc_natsio
docker rm mc_natsio

2.5 - Install Mosquitto MQTT Broker

Tested Versions

MyController tested on Mosquitto 1.6.9

Mosquitto broker can be installed in different way. Here we are focusing to setup it on docker and Mosquitto 1.6.9 version.

To install Mosquitto broker on your host system follow this guide

Note

Assuming that you are running all the commands as a root user.
If you are running from non-root user, you should include sudo in the beginning of the commands.

mosquitto.conf

Detailed information is on Mosquitto Website

# create mosquitto.conf
mkdir -p /opt/apps/mosquitto
cd /opt/apps/mosquitto

cat << EOF > mosquitto.conf
allow_anonymous true
persistence false
persistence_location /mosquitto/data/
EOF

Install

Variable $PWD

$PWD is a Print Working Directory.

mkdir -p /opt/apps/mosquitto
cd /opt/apps/mosquitto

docker run -d --name mc_mosquitto \
    --publish 1883:1883 \
    --publish 9001:9001 \
    --volume $PWD/mosquitto.conf:/mosquitto/config/mosquitto.conf \
    --restart unless-stopped \
    eclipse-mosquitto:1.6.9

To see the logs

Prints all available logs
```
docker logs mc_mosquitto
```
Prints and tails the logs, to get exit do Ctrl+C
```
docker logs --follow mc_mosquitto
```

Restart

docker restart mc_mosquitto

Uninstall

docker stop mc_mosquitto
docker rm mc_mosquitto

3 - Installation

Prerequisites

Prerequisites to setup MyController server

Metric Database
- Influx 1.8.x and above - Installation Guide
Optional requirements
- MongoDB
- MQTT broker - Mosquitto Installation Guide
- External bus service - nats.io Installation Guide

Installation

MyController.org 2.x can be installed in different way.

To know more about server setup follow this guide

3.1 - Quick Installation

You can install MyController in two different ways. You can either go with container image or executable binary.

3.1.1 - Install with container image

Install on Linux - Docker

Steps to install on your linux machine with docker

Note

Assuming that you are running all the commands as a root user.
If you are running from non-root user, you should include sudo in the beginning of the commands.

create directory for MyController server data and other usages

mkdir -p /opt/apps/mycontroller/mc_home
mkdir -p /opt/apps/mycontroller/mc_home/secure_share
mkdir -p /opt/apps/mycontroller/mc_home/insecure_share

copy mycontroller.yaml file

cd /opt/apps/mycontroller

curl https://raw.githubusercontent.com/mycontroller-org/backend/v2.0.0/resources/sample-docker-server.yaml \
  --output mycontroller.yaml

Update mycontroller.yaml file

IMPORTANT: update your secret on the mycontroller.yaml file. DO NOT USE THE DEFAULT SECRET
secret can between 1 to 32 characters length

This secret used to encrypt your third party password, tokens used on this server

secret: 5a2f6ff25b0025aeae12ae096363b51a # !!! WARNING: CHANGE THIS SECRET !!!

Update influx_database configuration as follows in your mycontroller.yaml

prior to this step, influxdb should be installed and running with a database called mycontroller in influxdb
Influxdb installation guide

IMPORTANT uri - must point to the influxdb host ip address

database:
  metric:
    disabled: false
    type: influxdb
    uri: http://192.168.1.21:8086 # must be updated with your host ip address
    token:
    username:
    password:
    organization_name:
    bucket_name: mycontroller
    batch_size:
    flush_interval: 5s

Optional - update bus configuration as follows in your mycontroller.yaml, if you plan to use external bus
- nats.io server should be installed and running
- nats.io server installation guide
- IMPORTANT server_url - must point to the nats.io server ip address.
```
bus:
  type: natsio
  topic_prefix: mc_communication_bus
  server_url: nats://192.168.1.21:4222 # must be updated with your host ip address
  insecure: false
  connection_timeout: 10s
```

Start the MyController server

docker run --detach --name mycontroller \
  --publish 8080:8080 \
  --publish 8443:8443 \
  --publish 9443:9443 \
  --volume $PWD/mc_home:/mc_home \
  --volume $PWD/mycontroller.yaml:/app/mycontroller.yaml \
  --env TZ="Asia/Kolkata" \
  --restart unless-stopped \
  docker.io/mycontroller/server:2.0.0

Access MyController server Web UI
- http://<host-ip>:8080 (example: http://192.168.1.21:8080)
- https://<host-ip>:8443 (example: https://192.168.1.21:8443)

To see the logs

Prints all available logs
```
docker logs mycontroller
```
Prints and tails the logs, to get exit do Ctrl+C
```
docker logs --follow mycontroller
```

Stop

docker stop mycontroller

Restart

docker restart mycontroller

Uninstall

docker stop mycontroller
docker rm mycontroller

3.1.2 - Install with executable binary

Install on Linux - Executable Binary

Steps to install the executable binary on your linux machine

Download Options

Choose the right executable bundle

Download the executable bundle that matches to your operating system architecture

Architectures

linux-arm - 32 bit ARM Linux
linux-arm64 - 64 bit ARM Linux
linux-386 - 32 bit Linux
linux-amd64 - 64 bit Linux
windows-386 - 32 bit Windows
windows-amd64 - 64 bit Windows

Download

Here we are focusing on arm architecture (Raspberry Pi). You can follows this guide for other architecture too.
Download mycontroller-server-2.0.0-linux-arm.tar.gz

Note

MyController server does not require root access, But for some devices(serial port, monitoring system resources, etc.,) it may required root access.
If you want to run MyController server with root, you should include sudo in the beginning of the commands. or directly run the commands as root user.

create a directories to keep MyController server data and executable

mkdir -p /opt/apps/mycontroller/mc_home  # directory to hold data
mkdir -p /opt/apps/mycontroller/executable # directory to hold executable

# create directories to keep image files to show it MyController dashboard
# Example, camera stream image
mkdir -p /opt/apps/mycontroller/mc_home/secure_share
mkdir -p /opt/apps/mycontroller/mc_home/insecure_share

# download the bundle and extract on executable directory
cd /opt/apps/mycontroller
wget https://github.com/mycontroller-org/server/releases/download/v2.0.0/mycontroller-server-2.0.0-linux-arm.tar.gz
tar xzf mycontroller-server-2.0.0-linux-arm.tar.gz  --strip-components=1 --directory /opt/apps/mycontroller/executable

now we have isolated MyController server data and executables, the expected result will be as follows,

NOTE: still, we have to keep the configuration file (mycontroller.yaml) file on the executable directory

$ ls /opt/apps/mycontroller/mc_home  # MyController server data location
insecure_share  secure_share

$ ls /opt/apps/mycontroller/executable # MyController server executable location
LICENSE.txt  logs  mcctl.sh  mycontroller-server  mycontroller.yaml  README.txt  web_console

Update mycontroller.yaml file

IMPORTANT: update your secret on the mycontroller.yaml file. DO NOT USE THE DEFAULT SECRET
secret can between 1 to 32 characters length

This secret used to encrypt your third party password, tokens used on this server

secret: 5a2f6ff25b0025aeae12ae096363b51a # !!! WARNING: CHANGE THIS SECRET !!!

update influxdb configuration as follows in your mycontroller.yaml
- prior to this step, influxdb should be installed and running with a database called mycontroller in influxdb
- Influxdb installation guide
- IMPORTANT uri - must point to the influxdb ip address. if you have installed on the same host, you can leave it as 127.0.0.1
- update other fields as per your influxdb setup
```
database:
  metric:
    disabled: false
    type: influxdb
    uri: http://127.0.0.1:8086 # must be updated with your host ip address
    token:
    username:
    password:
    organization_name:
    bucket_name: mycontroller
    batch_size:
    flush_interval: 5s
```
if you plan to use https with ACME(Letsencrypt) follow the detailed guide
Optional - if you plan to use external bus, update bus configuration as follows in your mycontroller.yaml
- nats.io server should be installed and running
- nats.io server installation guide
- IMPORTANT server_url - must point to the nats.io server ip address. if you have installed on the same host, leave it as 127.0.0.1
```
bus:
  type: natsio
  topic_prefix: mc_server
  server_url: nats://127.0.0.1:4222 # must be updated with your host ip address
  insecure: false
  connection_timeout: 10s
```

Start the MyController server

cd /opt/apps/mycontroller
executable/mcctl.sh start

Access MyController server Web UI
- http: http://<host-ip>:8080 (example: http://192.168.1.21:8080)
- https: https://<host-ip>:8443 (example: https://192.168.1.21:8443)

To see the logs

MyController log file is placed in the executable directory

cd /opt/apps/mycontroller
cat executable/logs/mycontroller.log

Prints and tails the logs, to get exit do Ctrl+C

cd /opt/apps/mycontroller
tail --follow executable/logs/mycontroller.log

Stop

cd /opt/apps/mycontroller
executable/mcctl.sh stop

Restart

cd /opt/apps/mycontroller
executable/mcctl.sh stop
executable/mcctl.sh start

Uninstall from your system

cd /opt/apps/mycontroller
executable/mcctl.sh stop
rm /opt/apps/mycontroller/executable --recursive --force

3.2 - Advanced Installation

TBD

3.2.1 - Backend Configuration

MyController backend configurations are loaded at the time of startup.
Configurations should be in the YAML file format.
Samples are available in the source code repository

Note

mycontroller.yaml file will not be included in the backup for the security reasons.

mycontroller.yaml

secret: 5a2f6ff25b0025aeae12ae096363b51a # (1)

analytics: # (2)
  enabled: true 

web: # (3)
  web_directory: /ui
  enable_profiling: false
  read_timeout: 60s
  http:
    enabled: true 
    bind_address: "0.0.0.0"
    port: 8080
  https_ssl:
    enabled: false
    bind_address: "0.0.0.0"
    port: 8443
    cert_dir: /mc_home/certs/https_ssl
  https_acme:
    enabled: false
    bind_address: "0.0.0.0"
    port: 9443
    cache_dir: /mc_home/certs/https_acme
    acme_directory:
    email: hello@example.com
    domains: ["mycontroller.example.com"]

logger: # (4)
  mode: record_all
  encoding: console
  level:
    core: info
    web_handler: info
    storage: info
    metric: warn

directories: # (5)
  data: /mc_home/data
  logs: /mc_home/logs
  tmp: /mc_home/tmp
  secure_share: /mc_home/secure_share
  insecure_share: /mc_home/insecure_share

bus: # (6)
  type: natsio
  topic_prefix: mc_production
  server_url: nats://192.168.1.21:4222
  insecure: false
  connection_timeout: 10s

gateway: # (7)
  disabled: false
  types: []
  ids: []
  labels:
    location: server

handler: # (8)
  disabled: false
  types: []
  ids: []
  labels:
    location: server

database: # (9)
  storage:
    type: memory
    dump_enabled: true
    dump_interval: 10m
    dump_dir: "memory_db"
    dump_format: ["yaml"] # options: yaml, json
    load_format: "yaml"

  metric:
    disabled: true
    type: influxdb
    uri: http://192.168.1.21:8086
    token: 
    username:
    password:
    organization_name: 
    bucket_name: mycontroller
    batch_size:
    flush_interval: 5s
    query_client_version:

secret is used to encrypt the password, token and other sensitive details in gateways, handlers, etc., and keep encrypted data in the storage database.
At later point if you change the secret you have update manually the existing passwords and tokens if any
Uses AES-256 encryption then base64 encoding
analytics if enabled, reports anonymous statics to MyController analytics collector
web holds the web configurations
logger - controls the logs level of a different components.
directories - points to custom locations.
bus - message bus configurations, will be used for internal communications.
gateway - filters to load gateways to this instance.
handler - filters to load handlers to this instance.
database - defines storage and metric configuration details

Web Configuration

web:
  web_directory: /ui # (1)
  documentation_url: http://192.168.1.21:8079/docs/ # (2)
  enable_profiling: false # (3)
  http: # (4)
    enabled: true 
    bind_address: "0.0.0.0"
    port: 8080
  https_ssl: # (5)
    enabled: false
    bind_address: "0.0.0.0"
    port: 8443
    cert_dir: /mc_home/certs/https_ssl
  https_acme: # (6)
    enabled: false
    bind_address: "0.0.0.0"
    port: 9443
    cache_dir: /mc_home/certs/https_acme
    acme_directory:
    email: hello@example.com
    domains: ["mycontroller.example.com"]

web_directory - production build of Web Console
documentation_url - if you are in a private environment and want to keep the document server locally. Add your documentation server url.
In MyController server default documentation url will be replaced with this url.
enable_profiling - enables GoLang profiling on the http handler at /debug/pprof/
http - HTTP handler
https_ssl - HTTPS SSL handler
https_acme - HTTPS ACME handler

HTTP handler

HTTP handler serves the web console and api as un-encrypted.
This setup can be used in a trusted network.

http:
  enabled: true # (1)
  bind_address: "0.0.0.0" # (2)
  port: 8080 # (3)

enabled - can enable or disable the http handler. if no values supplied, will be treated as disabled
bind_address - IP address to bind, 0.0.0.0 - binds to all the available network interfaces.
port - listening port number

HTTPS SSL handler

HTTPS SSL handler serves the web console and api as encrypted.
You can use self signed certificate or CA signed certificate.
You can use this handler to access the web console on the untrusted networks

https_ssl:
  enabled: false # (1)
  bind_address: "0.0.0.0" # (2)
  port: 8443 # (3)
  cert_dir: /mc_home/certs/https_ssl # (4)

enabled - can enable or disable the https ssl handler. if no values supplied, will be treated as disabled
bind_address - IP address to bind, 0.0.0.0 - binds to all the available network interfaces.
port - listening port number
cert_dir - certificate and key files location.

https_ssl operates in two modes.

Generate the certificates automatically
Custom certificate

Generate the certificates automatically

If there is no custom.crt and custom.key found on the cert_dir location MyController generates a crt and key files and stores on cert_dir location. Auto generated file names will as mc_generated.crt and mc_generated.key.

Auto generated certificate details:

RSA Bits - 2048
Organization name - MyController.org
Validity - 365 days

If you want to change these details, you have to generate a certificate manually as mentioned in Custom certificate

Custom certificate

If you want to use your custom certificates, you have to place your files on the cert_dir location. The name of the files must be as custom.crt and custom.key

To generate self signed certificate there are multiple options available. Here is a quick sample,

openssl genrsa -out custom.key 2048
openssl req -new -x509 -sha256 -key custom.key -out custom.crt -days 365

Important

If custom.crt and custom.key files are present in the cert_dir, it get the higher precedence than the auto generated files.

HTTPS ACME handler

Automated Certificate Management Environment (ACME) is a standard protocol for automating domain validation, installation, and management of X.509 certificates.
Letsencrypt is popular free certificate provider.

This handler can take care of the life cycle of the certificate. That is to get the certificate first time and subsequence renewals.

The default ACME directory url will be pointing to letsencrypt, https://acme-v02.api.letsencrypt.org/directory
The certificates will be renewed 30 days prior to expiration
ACME challenge will be verified using tls-alpn-01. Extra port is not required. To know more about tls-alpn-01 visit Letsencrypt guide
You have to configure port forward to the https_acme port. This port should be reachable on public ip of 443 port. acme challenge will be verified only on 443 port.

https_acme:
  enabled: false # (1)
  bind_address: "0.0.0.0" # (2)
  port: 9443 # (3)
  cache_dir: /mc_home/certs/https_acme # (4)
  acme_directory: # (5)
  email: hello@example.com # (6)
  domains: ["mycontroller.example.com"] # (7)

enabled - can enable or disable the https acme handler. if no values supplied, will be treated as disabled
bind_address - IP address to bind, 0.0.0.0 - binds to all the available network interfaces.
port - listening port number
cache_dir - certificate and related files received from the provider will be stored on this directory.
acme_directory - ACME provider directory url, if you leave it blank the default will be https://acme-v02.api.letsencrypt.org/directory
email - email address used to get the certificate from the provide
domains - You can have single or multiple domains

Logger

logger:
  mode: record_all # (1)
  encoding: console # (2)
  enable_stacktrace: false # (3)
  level: # (4)
    core: info
    web_handler: info
    storage: info
    metric: warn

mode - supports two modes.
- record_all - prints the detailed information about the log fields
- sampled - prints the restricted information about the log fields and not all the logs
encoding - log encoding format
- console - suits for console display
- json - prints logs in json format, suits for processing with external tools
enable_stacktrace - enables stack trace of the error
level - restrict the log level. supported levels: debug, info, warn, error, fatal. You can restrict the log level to a specific service.
- core - entire system log level. This is applicable for gateway service too.
- web_handler - http handlers log level
- storage service log level
- metrics service log level

Directories

directories:
  data: /mc_home/data # (1)
  logs: /mc_home/logs # (2)
  tmp: /mc_home/tmp # (3)
  secure_share: /mc_home/secure_share # (4)
  insecure_share: /mc_home/insecure_share # (5)

MyController uses these directories to keep configurations, logs, and temporary files.

data - keeps all configurations on this location. in-memory database, firmware, etc.,
logs - keeps gateway logs and system logs
tmp - used as a temporary location for MyController services
secure_share - you can keep custom files on this location. This location can be accessed via MyController instance url, http://mycontroller-ip:8080/secure_share. It needs authentication. access token can be supplied via header or on the url.
insecure_share - you can keep custom files on this location. This location can be accessed via MyController instance url, http://mycontroller-ip:8080/insecure_share. It is open to everyone. Authentication not required

Message Bus

bus:
  type: natsio # (1)
  topic_prefix: mc_production # (2)
  server_url: nats://192.168.1.21:4222 # (12)
  insecure: false # (3)
  connection_timeout: 10s # (4)

type - There are two type of message bus available.
- embedded - internal message bus. You cannot include external gateway
- natsio - external message bus
topic_prefix - A natsio message bus can be used for different applications. Based on this topics we can separate a specific MyController instance.
server_url - natsio server url
insecure - allow or disallow insecure connections
connection_timeout - connection establishment timeout

Important

When you use external gateway service. You should use external message bus service(natsio) Also should use the same message bus configurations in the MyController instance and in the external gateway instances.

Gateway

gateway:
  disabled: false # (1)
  types: [] # (2)
  ids: [] # (3)
  labels: # (4)
    location: server

We can restrict to load a specific gateway to this service.

disabled - enables or disables gateway service
types - filter specific gateway types
ids - filtered by list of gateways id
labels - filtered based on the labels. detailed guide

Note

Empty filter loads all the gateways.

Handler

handler:
  disabled: false # (1)
  types: [] # (2)
  ids: [] # (3)
  labels: # (4)
    location: server

We can restrict to load a specific handler to this service.

disabled - enables or disables handler service
types - filter specific handler types
ids - filtered by list of handlers id
labels - filtered based on the labels. detailed guide

Note

Empty filter loads all the handlers.

Database

You can define you storage and metric database configurations

database:
  storage:
    # storage database configurations
  metric:
    # metric database configurations

MyController needs two type of databases.

Storage
Metric

Storage Databases

MyController supports two type of storage databases

Memory
MongoDB

In Memory Database

In memory is a special database designed by MyController org. It keeps all the configuration data in the memory(RAM). Dumps all the data into the disk on a specified interval. When MyController start up, loads all the data from the disk to memory.

We can reduce the number of writes to disk. This can increase the life time of the disk.
This is very good choice for a tiny hardwares(ie: Raspberry PI with memory card as disk).
Memory database will be faster as the entities are in memory(RAM).

Important

Assuming dump enabled
When the MyController server terminated gracefully, dumps all the configuration data onto the disk.
So there will be no loss.
However there will be some loss, if the service terminated forcefully or power plug removed.

database:
  storage:
    type: memory # (1)
    dump_enabled: true # (2)
    dump_interval: 10m # (3)
    dump_dir: "memory_db" # (4)
    dump_format: ["yaml", "json"] # (5)
    load_format: "yaml" # (6)

type should be memory
dump_enabled - enable or disable sync to disk feature. Copies in memory entities into disk
dump_interval - how long once the sync should happen.
dump_dir - directory used to dump entities from memory. default: memory_db
dump_format - supports yaml and/or json formats.
load_format - even though you can dump entities on yaml and/or json format. at the time of startup, only one format can be used. Make sure you are using this format on the dump_format

MongoDB Database

MyController supports MongoDB local or cloud version.

type: mongodb # (1)
database: mcdb # (2)
uri: mongodb://192.168.1.21:27017 # (3)

type should be mongodb
database - name of the database in your MongoDB
uri of the database. supports cloud database format too.

Metric Databases

MyController supports two type of metric databases

Void
InfluxDB

InfluxDB

MyController uses InfluxDB to keep the metrics data. It can be local InfluxDB instance or can be in the cloud.
MyController supports InfluxDB 1.8.4 or above versions.

Note

Flux query supports for InfluxDB 1.8.x and InfluxDB 2.x,
however there is an issue on ARM architecture in mean and query functions
As a workaround, MyController uses two type of InfluxDB query clients.

v1 - uses InfluxQL query language
v2 - uses Flux query language

database:
  metric:
    disabled: false # (1)
    type: influxdb # (2)
    uri: http://192.168.1.21:8086 # (3)
    token: # (4)
    username: # (5)
    password: # (6)
    organization_name: # (7)
    bucket_name: mc_db # (8)
    query_client_version: # (9)
    batch_size: # (10)
    flush_interval: 1s # (11)

disabled if you want to disable metric database
type should be influxdb
uri is the database connection URI
token - authentication token used in InfluxDB 2.x
username - authenticate using username and password
password - authenticate using username and password. If username specified password is a mandatory field.
organization_name - used in InfluxDB 2.x
bucket_name - In influxdb 1.x it is a database name. In influxdb 2.x it is called bucket
query_client_version - MyController uses two type of query clients. It is recommended to keep it blank. MyController can choose automatically based the the database version used. However we can override the automatic selection by providing one for the option,
- v1 - InfluxDB 1.8.x
- v2 - InfluxDB 2.x
batch_size - sends the metrics to InfluxDB when meets the batch size
flush_interval - sends the metrics to InfluxDB when meets the interval

Sample of Cloud InfluxDB Configuration

database:
  metric:
    disabled: false
    type: influxdb
    uri: https://eu-central-1-1.aws.cloud2.influxdata.com
    token: VGhpcyBpcyBmYWtlIHRva2VuLCB0YWtlIHlvdXIgZnJvbSBNb25nb0RCIGNsb3VkCg==
    username: 
    password: 
    organization_name: example@example.com
    bucket_name: mc_bkt
    query_client_version: 
    batch_size: 
    flush_interval: 1s

Note

MongoDB Cloud offers free services for small applications.

3.2.2 - Gateway Configuration

MyController gateway configurations are loaded at the time of startup.
Configurations should be in the YAML file format.

gateway.yaml

Refer backend configuration detailed guide to know about the configurations

# This secret should be same as given in the server configuration file.
secret: 5a2f6ff25b0025aeae12ae096363b51a

directories:
  data: /mc_home/data
  logs: /mc_home/logs
  tmp: /mc_home/tmp

logger:
  mode: record_all
  encoding: console
  level:
    core: info
    storage: info
    metric: warn

bus:
  type: natsio
  topic_prefix: mc_production
  server_url: nats://192.168.1.21:4222
  insecure: false
  connection_timeout: 10s

gateway:
  disabled: false
  types: []
  ids: []
  labels:
    location: external_gw1

4 - User Interface

TBD

4.1 - Toolbar

Toolbar component contains various elements like filters, Action Buttons, Quick Buttons.
Toolbar will be placed on top of all the list resources page.
toolbar

Filters

filter1

By clicking the Filters button you can see the list of available filter options
Each filter is a field on the resource
Selecting more than one filter applies AND logic
By selecting a filter you can see one of the following filter
- Text input filter
- Selection filter
- Labels filter

Text input filter

This filter works in two different modes

Regex
- In this mode performs case insensitive and is the value contains search
Is In
- When supplying same option filter more than once, filter mode for that field switch to Is In
- Verifies that particular field has one of the input

Selection filter

This filter works same as Text input filter

Labels filter

Label filter is a special filter used to filter a resource by labels.
You can supply label in the format of key=value

Examples:

location=external
zone=south
version=2.0.2

Action Buttons

By selection one or more number of row, the action buttons drop down will be enabled
Selecting an action on the dropdown apply to all the selected resources

Quick Buttons

Couple of quick buttons will be on the toolbar
- - Refresh button, reloads the resources from the server
- - Add button, takes to add resource page

4.2 - Resources

resources

Resources are the key components in MyController.

Gateway

Gateway is the entry and exit point in MyController. It connects your network and MyController.

Node

Node is a kind of end point in the sensor world.

Source

Source is a single or group of fields

Field

Field is a final measurement point

Example

Take a couple ESP8266 boards
Those ESP8266 boards can be operated via MQTT protocol
Each board has sensors like, temperature, humidity, relay, push button, etc.,
Now relate with MyController resources
- All the boards can be connected via MQTT to MyController - is called gateway
- A board is a endpoint - is called node
- temperature, humidity, etc., measurements are called field
- group of fields or a single field goes under a source

4.2.1 - Gateway

MyController supports different type of providers network.
Each network can be connected to MyController via a gateway.
Gateway can be added/updated/deleted from the Resources >> Gateway page

Supported Providers list

Common Configurations

Form View
YAML View
```
id: mysensor # (1)
description: MySensors gateway # (2)
enabled: true # (3)
reconnectDelay: 15s # (4)
labels: # (5)
  location: core # (6)
```
1. id of the gateway. You cannot modify this field later
2. description of the gateway
3. enabled - You can enable or disable to disconnect from provider network.
4. reconnectDelay - if the gateway disconnected from the provider network for some reason, will be reconnected automatically after this delay
5. labels - labels are a key value pair used across the system
6. labels.location this is a kind of filter used to restrict to run this gateway to a specific location(s)

Note

The id field can not be changed later

Power of the labels

We can restrict to load a gateway to the specific host.

For example you are running gateway service on multiple hosts and all the gateway service connected to MyController via message bus. you have connected a serial port on Host B. When you add a gateway configuration on MyController, it sends the configuration details to all the gateway listener services. So all the gateway listeners are try to look that serial port on their hosts. expect from Host B all other gateway reports failed to load. To avoid these kind of situation, we have introduced labels. When we start a gateway service on a host, include label based filter. That gateway service listens only it is own configuration.

gateway setup

In the above setup, if we include labels as location=gw2 on the configuration, It loads on the Host C gateway service. Other gateways from the different hosts will ignore this configuration.

Provider Configurations

Message Logger Configurations

Message logger is recording received and transmitted messages.

Type of Message Logger

None - disable message logging system
File Logger - records the messages into a file (disk)

Note

This feature is available for all selected providers.

Form View
YAML View
```
 messageLogger:
  type: file_logger # (1)
  flushInterval: 5s # (2)
  logRotateInterval: 6h # (3)
  maxSize: 1MiB # (4)
  maxAge: 24h # (5)
  maxBackup: 3 # (6)
```
1. messageLogger.type message logger type. support file_logger and none
2. messageLogger.flushInterval how long once received message to be dumped to disk from memory
3. messageLogger.logRotateInterval creates new file after this interval
4. messageLogger.maxSize if the size reaches the maxSize, creates new file
5. messageLogger.maxAge if the age reaches the maxAge, creates new file
6. messageLogger.maxBackup retention files count

4.2.2 - MySensors

MySensors is an open source hardware and software community focusing on do-it-yourself home automation and Internet of Things. To know more about MySensors network follow this link

Provider Specific key points

In a network MySensors can have maximum of 254 nodes
node id 0 is always a gateway node
node id 1 to 254 can be allocatable to any node
Supported features in MyController
- OTAfeatures / Firmware update
- reboot a node
- reset a node
- get a node info
- discover nodes
- Heartbeat request
- Response to internal message like I_TIME, I_CONFIG, I_ID_REQUEST
- Assigns NodeId if nodeId set as AUTO on a node

Not implemented / supported features (that is supported on MyController 1.x)

Handle sleeping nodes
There is no node alive check

Common Configuration

Form view
YAML View
```
provider:
  type: mysensors_v2 # (1)
  enableInternalMessageAck: true # (2)
  enableStreamMessageAck: false # (3)
  retryCount: 3 # (4)
  timeout: 1s # (5)
```
1. type should be selected as mysensors_v2
2. enableInternalMessageAck enable acknowledgement for internal messages
3. enableStreamMessageAck enable acknowledgement for streaming messages. ie: OTA/firmware messages
4. retryCount - if do not receive the acknowledgement on the specified timeout, keeps resend the message till it reaches the retryCount
5. timeout - wait for the acknowledgement till this timeout

Protocols

MySensors gateway supports the following protocols

MQTT
Serial
Ethernet

Protocol Configuration - MQTT

Form view
YAML View
```
provider:
  protocol:
    type: mqtt # (1)
    transmitPreDelay: 15ms # (2)
    broker: tcp://192.168.1.21:1883 # (3)
    insecureSkipVerify: false # (4)
    username: '' # (5)
    password: '' # (6)
    subscribe: out_rfm69/# # (7)
    publish: in_rfm69 # (8)
    qos: 0 # (9)
```
1. type type of the protocol. here it should be mqtt
2. transmitPreDelay - wait till this time to avoid collision and sends the data to provider network
3. broker mqtt broker url
4. insecureSkipVerify if you want to skip the insecure ssl, enable this option
5. username username of the mqtt broker. if it is anonymous leave it as a blank
6. password if username supplied, password should be supplied. otherwise leave it as a blank
7. subscribe topic to be subscribed to get messages from MySensors gateway
8. publish topic to be used to post data from MyController to MySensors network
9. qos MQTT qos

Note

It is important to include /# at the end of subscription topic to receive from all the nodes. example: out_rfm69/#

Protocol Configuration - Serial

Form view
YAML View
```
provider:
  protocol:
    type: serial # (1)
    transmitPreDelay: 15ms # (2)
    portname: /dev/ttyUSB0 # (3)
    baudrate: 115200 # (4)
```
1. type of the protocol. here it should be serial
2. transmitPreDelay - wait till this time to avoid collision and sends the data to provider network
3. portname name of the serial port
4. baudrate baud rate of the serial port

Protocol Configuration - Ethernet

Form view
YAML View
```
provider:
  protocol:
    type: ethernet # (1)
    transmitPreDelay: 15ms # (2)
    server: tcp://192.168.1.42:5000 # (3)
    insecureSkipVerify: false # (4)
```
1. type of the protocol. here it should be ethernet
2. transmitPreDelay - wait till this time to avoid collision and sends the data to provider network
3. server ethernet server address with port
4. insecureSkipVerify if you want to skip the insecure ssl, enable this option

4.2.3 - Tasmota

Tasmota is an Open source firmware for ESP8266 devices

Common Configuration

Form view
YAML View
```
provider:
  type: tasmota # (1)
```
1. type should be selected as tasmota

Protocols

Tasmota gateway supports the following protocols

MQTT

Protocol Configuration - MQTT

Form view
YAML View
```
provider:
  protocol:
    type: mqtt # (1)
    transmitPreDelay: 15ms # (2)
    broker: tcp://192.168.1.21:1883 # (3)
    insecureSkipVerify: false # (4)
    username: '' # (5)
    password: '' # (6)
    subscribe: jktasmota/# # (7)
    publish: jktasmota # (8)
    qos: 0 # (9)
```
1. type type of the protocol. here it should be mqtt
2. transmitPreDelay - wait till this time to avoid collision and sends the data to provider network
3. broker mqtt broker url
4. insecureSkipVerify if you want to skip the insecure ssl, enable this option
5. username username of the mqtt broker. if it is anonymous leave it as a blank
6. password if username supplied, password should be supplied. otherwise leave it as a blank
7. subscribe topic to be subscribed to get messages from MySensors gateway
8. publish topic to be used to post data from MyController to MySensors network
9. qos MQTT qos

Note

It is important to include /# at the end of subscription topic to receive form all the nodes. example: jktasmota/#

MQTT configuration on the Tasmota node

tasmota-node

The following changes needs to be updated on the Tasmota node MQTT settings to connect with MyController

Topic - should be updated as tasmota_%06X
Full Topic - should be updated as jktasmota/%prefix%/%topic%/
- here jktasmota can be any name, should be in lowercase and special characters are not allowed

To know more about MQTT settings on Tasmota follow this guide

4.2.4 - PhilipsHue

PhilipsHue is smart home lighting.
To know more about PhilipsHue developer API follow this link

Configuration

Form view
YAML View
```
provider:
  type: philips_hue # (1)
  host: http://192.168.1.34:80 # (2)
  username: myhueuser # (3)
  syncInterval: 10m # (4)
  bridgeSyncInterval: 10m # (5)
```
1. type should be selected as philips_hue
2. host - PhilipsHue bridge address to communicate
3. username of the PhilipsHue bridge
4. syncInterval - polls the connected devices status from the PhilipsHue bridge
5. bridgeSyncInterval - gets the PhilipsHue bridge configurations on this interval

4.2.5 - System Monitoring

System Monitoring is an internal plugin developed and maintained by MyController

Configuration

Form view
YAML View
```
provider:
  type: system_monitoring # (1)
  hostIdMap: {} # (2)
  hostConfigMap: {} # (3)
```
1. type should be selected as system_monitoring
2. hostIdMap - is a group of key value map
3. hostConfigMap configurations of monitoring resources

Host ID Map Configuration

Host ID Map (hostIdMap) is used to map the real host id with a friendly name

Samples:

be0164ad-6f25-4448-b691-567946392b47: rpi_1
a574ac8d-4c9f-40d6-b0ce-bbc7d98cd87d: rpi_2

Here be0164ad-6f25-4448-b691-567946392b47 is the actual id of the host and it is mapped with rpi_1. If data received from this node, The node name will be as rpi_1

Host Config Map Configuration

Host Config Map (hostConfigMap) is used to configure a specific node(s)

rpi_1: # (1)
  disabled: false # (2)
  cpu: # (3)
    interval: 1m
    cpuDisabled: false
    perCpuDisabled: false
  disk: # (4)
    interval: 1h
    disabled: false
    data:
      disk_root:
        disabled: false
        name: "Root"
        path: /root
        unit: MiB
      disk_storage:
        disabled: false
        name: "Storage"
        path: /storage
        unit: MiB
  memory: # (5)
    interval: 1m
    memoryDisabled: false
    swapMemoryDisabled: false
    unit: MiB
  process: # (6)
    interval: 1m
    disabled: false
    data:
      influxd:
        disabled: false
        name: "InfluxDB"
        unit: MiB
        filter:
          cmdline: influxd
      adguard:
        disabled: false
        name: "AdGuard"
        unit: MiB
        filter:
          cmdline: >-
            /opt/adguardhome/AdGuardHome --no-check-update -c
            /opt/adguardhome/conf/AdGuardHome.yaml -h 0.0.0.0 -w
            /opt/adguardhome/work            
      mycontroller:
        disabled: false
        name: "MyController"
        unit: MiB
        filter:
          cmdline: /app/mycontroller-all-in-one -config /app/mycontroller.yaml
      natsio:
        disabled: false
        name: "NatsIO"
        unit: MiB
        filter:
          cmdline: nats-server --config /etc/nats/nats-server.conf
      proc_gw:
        disabled: false
        name: "MYC GW"
        unit: MiB
        filter:
          cmdline: ./mycontroller-gateway -config gateway.yaml
  temperature: # (7)
    disabledAll: false
    interval: 30s
    enabled: []
rpi_2: # (1)
  cpu:
    # ...

node_id - id of the node or host
disabled - set true to disable data from this node. default value: false
cpu configurations
disk configurations
memory configurations
process configurations
temperature configurations

CPU Configurations

cpu:
  interval: 1m # (1)
  cpuDisabled: false # (2)
  perCpuDisabled: false # (3)

interval - metric measurement interval
cpuDisabled - disable overall CPU metrics data
perCpuDisabled - disable individual CPU(s) metrics data

Disk Configurations

disk:
  interval: 1h # (1)
  disabled: false # (2)
  data: # (3)
    disk_root: # (4)
      disabled: false # (5)
      name: "Root" # (6)
      path: /root # (7)
      unit: MiB # (8)
    disk_storage:
      disabled: false
      name: "Storage"
      path: /storage

interval - metric measurement interval
disabled - disable the all the disk metrics
data - is a map of disk configurations
This id will be used as fieldId in MyController, use lowercase, no special characters, _ allowed
disabled - disable this particular disk metrics
name - will be used as field name
path - disk path used to measure the usage details
unit - units guide

Memory Configurations

memory:
  interval: 1m # (1)
  memoryDisabled: false # (2)
  swapMemoryDisabled: false # (3)
  unit: MiB # (4)

interval - metric measurement interval
memoryDisabled - enable/disable memory measurement
swapMemoryDisabled - enable/disable swap measurement
unit - units guide

Process Configurations

process:
  interval: 1m # (1)
  disabled: false # (2)
  data: # (3)
    influxd: # (4)
      disabled: false # (5)
      name: "InfluxDB" # (6)
      unit: MiB # (7)
      filter: # (8)
        cmdline: influxd # (9)
    mycontroller:
      disabled: false
      name: "MyController"
      filter:
        cmdline: /app/mycontroller-all-in-one -config /app/mycontroller.yaml

interval - metric measurement interval
disabled - disable the all the process metrics
data - is a map of process configurations
This id will be used as fieldId in MyController, use lowercase, no special characters, _ allowed
disabled - disable this particular process metrics
name - will be used as field name
unit - units guide
filter - used to get a specific filter
cmdline - one of the key used to filter a process

Supported keys in the filter

pid - Process ID
cmdline -
cwd - client’s Current Working Directory
exe -
name -
nice - nice value of the process
ppid - Parent Process ID
username -

Measurement Units

Bye default all the values reported in bytes. We have an option to convert the bytes to more readable values.
Update unit on the supported resources.
If you want the values in bytes leave the unit field as blank or remove it completely

Supported units: KiB, MiB, GiB, TiB, PiB, EiB

KiB - Kibibytes (1024¹ bytes)
MiB - Mibibytes (1024² bytes)
GiB - Gibibytes (1024³ bytes)
TiB - Tebibytes (1024⁴ bytes)
PiB - Pebibytes (1024⁵ bytes)
EiB - Exbibytes (1024⁶ bytes)

Note

Units are case sensitive. If the specified unit is not in the above list, returns the value as bytes

4.3 - Dashboard

TBD

4.4 - Operations

TBD

4.4.1 - Tasks

TBD

4.4.2 - Schedules

Holds a collection of schedules. Schedules are executed by a scheduler service.
Schedule can bse used for different use cases.
The most famous one is turn ON a light at specific time and turn OFF a light at a specific time.
But in MyController it is not limited to lights. You can control variety of resources.

Schedule has a different sections. All the sections are explained here.

Important

Schedules will be executed based on the system timezone.
If you change the system timezone, it is mandatory to restart the MyController service.

Identity

Form View

id and description

YAML View

id: my_first_schedule # (1)
description: This is my first schedule # (2)
enabled: true # (3)

id - should be a unique identifier
description - add description about this schedule
enabled - enable/disable this schedule

Labels

You can add any number of labels. Labels can be used to filter a group of schedule.
Labels can be used to perform an action on a group schedules.

Form View

labels

YAML View

labels:
  group: essential

Validity

Validity is a special feature. You can control when this schedule should be effective.
All the fields are optional. By omitting a field gives different meanings

To get activate this feature validity should be enabled

Date and Time

Based on the given fields, validity reacts as follows,

If non of the fields entered - valid for all the time.
date.from - schedule will be valid from the given from date.
There is no from time entered here, but from date is available. Hence from.time will be calculated as 00:00:00
Example: 2021-09-16 becomes 2021-09-16 00:00:00
date.to - schedule will be valid till the given to date.
There is no to time entered here, but to date is available. Hence to.time will be calculated as 23:59:59
Example: 2021-09-24 becomes 2021-09-24 23:59:59
date.from, time.from - schedule will be valid from the given from date and from time.
date.to, time.to - schedule will be valid till the given to date and to time.
date.from, date.to, time.from, time.to - schedule can be valid between the from date/time ~ to date/time.
validateTimeEveryday => Disabled - valid exactly from date/time ~ to date/time.
Example: 2021-09-16 11:15:00 to 2021-09-24 19:00:00
validateTimeEveryday => Enabled - between these date and the time valid for every day.
Example: between2021-09-16 to 2021-09-24 - time is valid for every day between 11:15:00 to 19:00:00

Form View

validity

YAML View

validity:
  enabled: true
  date:
    from: '2021-05-14'
    to: '2021-06-21'
  time:
    from: '00:00'
    to: '23:59'
  validateTimeEveryday: false

Schedule Type

Schedule supports different types.

Repeat
Cron
Simple
Sunrise
Sunset

Repeat

Repeat is a super simple schedule.

Executes the schedule on the specified interval till it reaches the repeat count.
Set repeat count to 0 to keep on repeating.

Note

Very first execution starts after the given interval.

Cron

Cron is a time-based job scheduler in Unix-like computer operating systems.
In MyController in addition to that, it supports seconds field.
Refer Cron wikipedia page to know more about cron.

┌───────────── second (0 - 59)
| ┌───────────── minute (0 - 59)
│ | ┌───────────── hour (0 - 23)
│ | │ ┌───────────── day of the month (1 - 31)
│ | │ │ ┌───────────── month (1 - 12)
│ | │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday;7 is also Sunday on some systems)
│ | │ │ │ │                                   
│ | │ │ │ │
│ | │ │ │ │
* * * * * *

The first field second is optional, you can omit it.
Also supports @yearly, @monthly, @weekly, @daily (or @midnight), @hourly

Simple

Simple is a friendly schedule type.
It supports different type of frequencies.

Daily
Weekly
Monthly
On Date

Schedule executes on the specified time, if the day meets the specified frequency.
Time can be specified in the format of hh:mm:ss. hours should be in 24 hours format
Examples:

05:00:00 - 5 AM
12:30:20 - 12:30:20 PM
17:15:00 - 5:15 PM

Frequency - Daily

In this mode you can restrict the schedule to the selected week days.

Possible select multiple days of a week.
Schedule executes on the selected days of the week.

Frequency - Weekly

In this mode you can restrict the schedule to particular week day.

Select a day in week.
Schedule executes on the selected day of the week.
In simple words, only once in a week.

Frequency - Monthly

In this mode you can restrict the schedule to particular day of month.

Select a date in a month
Schedule executes on the selected date of the month
In simple words, only once in a month

Note

If you select non-common date, ie: 29, 30, and 31
The schedule execution will be skipped for a month, if it does not have the date mentioned above.

Frequency - On Date

In this mode you can restrict the schedule to particular date and time.

This schedule executes only once in a life time.

Sunrise

Sunrise works similar to Simple schedule, expect the time part.
Here explained only about the time part. refer Simple schedule for other options.

Based on the GEO Location configured for the system, Sunrise time will be calculated. This calculation happens every day at midnight of the system timezone.

Offset

Offset used to calculate the exact time to execute the schedule.
Offset is a time duration. Refer duration guide for the detailed information.

Examples:

10m - executes 10 minutes after the sunrise time
-10m - executes 10 minutes before the sunrise time
1h20m - executes 1 hour and 20 minutes after the sunrise time
-1h20m - executes 1 hour and 20 minutes before the sunrise time

Sunset

Sunset works similar to Simple schedule, expect the time part.
Here explained only about the time part. refer Simple schedule for other options.

Based on the GEO Location configured for the system, Sunset time will be calculated. This calculation happens every day at midnight of the system timezone.

Offset

Offset used to calculate the exact time to execute the schedule.
Offset is a time duration. Refer duration guide for the detailed information.

Examples:

10m - executes 10 minutes after the sunset time
-10m - executes 10 minutes before the sunset time
1h20m - executes 1 hour and 20 minutes after the sunset time
-1h20m - executes 1 hour and 20 minutes before the sunset time

Load variables

Load variables is an optional configuration.
Follow Load Variables Guide for the detailed configuration.

Use variables when you want to,

play with Javascript
enable or disable Parameters to handler

Load Custom Variables

Sometimes you may want to do some calculations or based on a value you want to set something, In those cases Load Custom Variables will be used.

Types

None
Javascript
Webhook

None

Whe you do not want to use Load Custom Variables feature, use None option.

Javascript

Follow Javascript Guide for the details.

Webhook

Follow Webhook Guide for the details.

Parameters to Handler

Follow Parameters to Handlers Guide for the detailed configuration.

Notify Handlers

Follow Notify Handlers Guide for the detailed configuration.

4.4.3 - Handlers

Handlers are performing an action based on the input parameters.
Different type of handlers supported by MyController.
Handler is a plugin component.

Note

Some of the configurations in the handler can be overrides by the input parameters.

Noop Handler

Noop is a No Operation handler. It does nothing.
The idea behind Noop handler is, in the future plan to introduce hidden handlers externally.
Right now, there is no use.

Resource Handler

Resource handler sends payload to the nodes, performs an actions on resource, operation, etc.,

Email Handler

Sends email to the recipients. Supports smtp server.

Form View

email handler

YAML View

type: email # (1)
spec:
  host: smtp.example.com # (2)
  port: 465 # (3)
  insecureSkipVerify: true # (4)
  username: username@example.com # (5)
  password: mypassword # (6)
  fromEmail: from@example.com # (7)
  toEmails: to1@example.com,to2@example.com # (8)

type should be selected as email
host - email server host
port - email server port
insecureSkipVerify - enables/disables insecure
username of the account
password of the account
fromEmail from email address
toEmails to emails list comma separated

Telegram Handler

Sends telegram message to persons and/or groups.
Follow this guide to get the telegram token, chat_id and group_id

Form View

telegram handler

YAML View

type: telegram # (1)
spec:
  token: 500000000:AAHKsdsdckwendlwwqNKJBmbjknm9jA # (2)
  chatIds: # (3)
    - '200000000'
    - '300000000'

type should be selected as telegram
token of the telegram account
chatIds - list of chat ids or group ids

Backup Handler

Backup handler performs backup operation and keeps the backup archives at the specified target location

Important

Backup covers only the storage database and firmware’s.
Metrics data will not be backed up.
User has to handle metrics database backup/restore themselves.

Form View

backup handler

YAML View

type: backup # (1)
spec:
  providerType: disk # (2)
  spec:
    storageExportType: yaml # (3)
    targetDirectory: /mc_home/backups/ # (4)
    prefix: primary # (5)
    retentionCount: 10 # (6)

type should be selected as backup
providerType should be selected as disk. Only this provider supported now
storageExportType - storage database data will be exported in this format. options: yaml, json
targetDirectory - location to keep the backup archives
prefix of the backup file
retentionCount - If the number of backup archives goes beyond this count,older files will be deleted permanently.

4.4.4 - Forward Payload

Forward Payload sends the payload from a source field to destination field.
Supports only for the Field resource.

Navigate to Operations >> Forward Payload
Click on Add button

Form View

On the Source Field and Destination Field type Field ID, displays matching ids as a dropdown.

YAML View

id: forward_water_level # (1)
description: Sends tank water level to display node # (2)
enabled: true # (3)
srcFieldId: field:mysensor.1.1.V_VOLUME # (4)
dstFieldId: field:mysensor.13.1.V_VOLUME # (5)

id - should be unique across forward payload
description of the entity
enable - enable/disable this entry
srcFieldId - source field id
dstFieldId - destination field id

4.4.5 - Load Variables

Load Variables is a sub configuration in a Task or in a Schedule.
You can load any number of variables for the further operations.

Form View

load variables

Variable Name is used a internal reference for further operations. should be unique.
Add new variable click + icon
To delete a variable click - icon
By clicking edit icon of a value, can offer to select different data types.

YAML View

In YAML view, the data is encoded with base64 format to avoid syntax issues.

variables:
  water_level: >-
    {"type":"resource_by_quick_id","disabled":"","data":"cmVzb3VyY2VUeXBlOiBmaWVsZApxdWlja0lkOiBteXNlbnNvci4xLjEuVl9WT0xVTUUKc2VsZWN0b3I6IGN1cnJlbnQudmFsdWUK"}    
  motor_status: >-
    {"type":"resource_by_quick_id","disabled":"","data":"cmVzb3VyY2VUeXBlOiBmaWVsZApxdWlja0lkOiBteXNlbnNvci4xMy4xLlZfU1RBVFVTCnNlbGVjdG9yOiBjdXJyZW50LnZhbHVlCg=="}

Data Types

Following data types are supported in Load Variables.

String
Resource By QuickID
Resource By Labels

String

String is static type. It assigns the given value to that variable.

Resource By QuickID

Resource can be selected by their QuickID.

Form View

load variable by quick id

Select a Resource Type
enter the id of the resource, you will get a list of matching resources. Select a resource.
On the Selector field enter the exact path to get value. See Selector Guide

YAML View

type: resource_by_quick_id
data:
  resourceType: field
  quickId: tasmota.tasmota_0B8E60.Control.POWER
  selector: current.value

Resource By Labels

Resource can be selected by their Labels.

Note

If a list of resources received, the very first resource will be taken for further actions.

Form View

load variable by quick id

Select a Resource Type
enter key value of a label. enter as many labels you want.
On the Selector field enter the exact path to get value. See Selector Guide

YAML View

type: resource_by_labels
data:
  resourceType: field
  labels:
    location: hall
  selector: current.value

Selector

Selector is dot(.) separated path used to select a value on the given resource.
If the path not found returns empty value.
To make the path, you should know the supported keys on a resource.

To know more about supported keys of a resource,

go to that particular resource details page
click on edit
select the YAML View.

Some of the references

Resource - Field

current.value - current value
current.timestamp - current value received timestamp
noChangeSince - There is no change on the received value from this time
previous.value - previous value
previous.timestamp - previous value received timestamp

Resource - Gateway

state.status - status of the gateway. can be up, down, error, etc.,
enabled - enabled or disabled

4.4.6 - Parameters to Handler

Parameters used to send a configuration to handlers.
Based on the the given configuration(via parameter) handler reacts

Form View

parameters to handler

Parameter has two fields,

to add new parameter click + icon
to remove a parameter click - icon
Name of the field should be unique. There is no special meaning for the name. use it as your reference.
Value - value can be one of the type mentioned here. To update a value click on edit icon

YAML View

In YAML view, the data is encoded with base64 format to avoid syntax issues.

handlerParameters:
  run_backup: >-
    {"type":"backup","disabled":"","data":"cHJvdmlkZXJUeXBlOiBkaXNrCnNwZWM6CiAgc3RvcmFnZUV4cG9ydFR5cGU6IHlhbWwKICByZXRlbnRpb25Db3VudDogNQogIHRhcmdldERpcmVjdG9yeTogJycKICBwcmVmaXg6ICcnCg=="}    
  turn_on_light: >-
    {"type":"resource_by_quick_id","disabled":"","data":"cmVzb3VyY2VUeXBlOiBmaWVsZApxdWlja0lkOiB0YXNtb3RhLnRhc21vdGFfODg3NDIxLkNvbnRyb2wuUE9XRVIKcGF5bG9hZDogJ29uJwpwcmVEZWxheTogMTBzCg=="}

Parameter Types

Parameter types are based on the supported handlers.

Resource By Quick ID
Resource By Labels
Webhook
Email
Telegram
Backup

Disabled is a common field across all type of parameters.

a parameter can be enabled or disabled dynamically.
can be disabled by setting this field as true
default value for this field is false

Note

All the parameter values supports template.
With template we can update the value or part of the value dynamically.
Template Guide

Resource By Quick ID

Resource can be selected by their QuickID.

Form View

resource by quick id

Select a Resource Type
enter the id of the resource, you will get a list of matching resources. Select a resource.
on the payload update the action or value you want to set to the selected resource
Pre Delay is used to wait some time and perform the action. 10s - Resource handler waits 10 seconds and sets this value.

Note

Pre delay parameters will be lost on the intermediate restart of the MyController server.
Example:

You passed a resource parameter with pre delay as 1 hour.
The parameter passed to resource handler service and this handler can perform the resource action exactly after 1 hour.
This data is in resource handler service memory.
If you restart your MyController service, that particular action will be lost and will not be executed.

YAML View

disabled: ''
type: resource_by_quick_id
data:
  resourceType: field
  quickId: tasmota.tasmota_887421.Control.POWER
  payload: 'on'
  preDelay: 10s

Resource By Labels

This is exactly same as Resource By Quick ID.
The only different is, selecting resources by Labels
When filtering with labels it possible to get more than on resource.
Particular action will be applied to all the resources filter by labels.

Form View

resource by labels

YAML View

disabled: ''
type: resource_by_labels
data:
  resourceType: field
  labels:
    group: lights
  payload: 'on'
  preDelay: 0s

Webhook

TBD

Email

All the fields in email parameter is optional.
If non of the fields entered here, taking all the fields from the Email Handler
The field enter here is taken, for empty values updates from the Email Handler

Form View

resource by quick id

YAML View

disabled: ''
type: email
data:
  from: example@example.com
  to:
    - example1@example.com
    - example2@example.com
  subject: 'Alert: Overheat detected on CPU'
  body: |-
    Alert: Overheat detected on CPU.
    Check the status of the CPU Fan.

other than the Text all the fields are optional
empty values are taken from Telegram Handler
telegram supports different Text parse modes, Text, Markdown, Markdown V2, HTML.

Important

All the syntax are supported from Markdown, Markdown V2, HTML.
Refer Telegram API Guide for the detailed format options.

Form View

resource by quick id

YAML View

disabled: ''
type: telegram
data:
  chatIds:
    - '20000000'
    - '-4000000'
  parseMode: Text
  text: |-
    Alert: Overheat detected on CPU.
    Check the status of the CPU Fan.

Backup

Backup parameter used to execute a backup via a schedule or from a task.

Other than the Provider and Retention Count, all other inputs are optional
empty values are taken from the Backup Handler
If you enter Retention Count as 0, the value will be taken from the Backup Handler

Restore

To restore a backup follow the Restore Guide

Form View

resource by quick id

YAML View

disabled: ''
type: backup
data:
  providerType: disk
  spec:
    storageExportType: yaml
    targetDirectory: /mc_home/backups
    prefix: scheduled
    retentionCount: 10

4.4.7 - Notify Handlers

Handlers should be created prior to this section. Follow Handlers Guide to create a handler.

Notify handlers holds a list of handler ids. Sends all the parameters to the specified handler services.
Based on the Parameters type a particular Handler service can filters supported type(s) and executes it.

Form View

notify handlers

Click + icon to add new handler id
Click - icon to delete a handler id

YAML View

handlers:
  - telegram_home_group
  - resource_handler

4.4.8 - Javascript

TBD

4.4.9 - Webhook

TBD

4.4.10 - Template

TBD

4.5 - Settings

TBD

4.5.1 - System

The system settings has the following configurations

GEO Location
Login Page

GEO Location

GEO Location address the current location of the server or ask to follow the given location as server location and operate dependent services.
This detail used to calculate Sunrise and Sunset times in Schedule

Form View

geo location

Auto Update - Enabling this field can take the server location based on the WAN IP address.
If you want to give the value manually, disable this field.
Location Name - Name of the location
Latitude of the location
Longitude of the location

YAML View

geoLocation:
  autoUpdate: false
  locationName: Namakkal
  latitude: 11.2189165
  longitude: 78.1586027

You can enter a message to display on the login page of the console.
The message supports HTML tags.

Form View

YAML View

login:
  message: |-
    This is a private MyController instance. Running in a local Raspberry PI
    <br>Default username and password: admin / admin

4.5.2 - Backup and Restore

Backup

Restore

5 - Appendix

TBD

5.1 - Setup Telegram Bot

This document helps to setup your telegram to receive messages from MyController.
MyController needs a telegram token and a chat id and/or group id to send a messages.

Create a bot and generate a token
Get user chat id
Get group id

Create a telegram bot

Open Telegram messenger, sign in to your account or create a new one.

Enter @Botfather in the search tab and choose this bot.
Note: official Telegram bots have a blue checkmark beside their name
Click START to activate BotFather bot. In response, you receive a list of commands to manage bots.
Choose or type the /newbot command and send it.
Choose a name for your bot. And choose a username for your bot, the bot can be found by its username in searches. The username must be unique and end with the word bot
After you choose a suitable name for your bot, the bot is created. You will receive a message with a link to your bot t.me/<bot_username>, recommendations to set up a profile picture, description, and a list of commands to manage your new bot.
To connect a bot to MyController you need a token. Copy your token value and add it in to Telegram handler.

Get user chat id

User chat id can be extracted via API or with a supported bot.
Here the details are given to get chat id via MyController.org bot

On your telegram application on the search input enter mycontroller_org_bot.
You can see MyController.org bot bot as shown blow.
Click on the START to get connect with MyController.org bot
MyController.org bot info will be as below,
Send a text chat id, you will get a response with your chat_id

Get group chat id

Group id can be extracted via API or with a known bot.
Here the details are given to get group id via MyController.org bot

Open your group and click on Add members
on the search input type mycontroller_org then select MyController.org bot and click on ADD
Send a text chat id, you will get a response with your group_id and chat_id