This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Operations

1: Tasks
2: Schedules
3: Handlers
4: Forward Payload
5: Load Variables
6: Parameters to Handler
7: Notify Handlers
8: Javascript
9: Webhook
10: Template

TBD

1 - Tasks

TBD

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.

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 - 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

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

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

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

8 - Javascript

TBD

9 - Webhook

TBD

10 - Template

TBD