mO SharemO Share

SiteController.cfg

Introduction

The configuration of the Site Controller is the most important part in getting the system up and running. This article will go into every detail of the configuration file and explain it thouroughly. If you just wish to install the Site Controller quickly, then please refer to our installtion guide and the Get Started page.

In the more detailed part, we will only go through the parts of the config file, which in normal use cases might be changed. A lot of the parameters will mostly not be touched by the user or might even be obsolete and are only in there for previous versions.

On this page:

Example Configuration File

The default directory to the SiteController.cfg is /opt/azeti/SiteController/foobar

[General]
# Allowed characters for the serial are upper and lower case ASCII [a-zA-Z],
# digits [0-9], dashes - and underlines _ only!
serial=azetiDemo
listenOn=
mqtt_version=MQTTv311
timezone=Etc/UTC
# DO NOT CHANGE base_defaults_id MANUALLY!
base_defaults_id=8464a79
# server_sysconfig_revision is for server feedback purposes - has no impact on SC operation
server_sysconfig_revision=13

outbox_check_interval_seconds=30
outbox_persist_interval_seconds=60
outbox_confirm_published_timeout_seconds=600
dbPath=/opt/azeti/SiteController/persistent
default_logger=azeti_file

[InternalBroker]
host=127.0.0.1
sub_topics=events/#, hd/#, config_backup/#, sys_msg/#, imgdata/#, vs_data/+/backup

[ExternalBroker]
host=azetibroker02.azeti.net
reconnect_delay=1
reconnect_delay_max=300
reconnect_exponential_backoff=True
organizationShortName=azeti
sub_topics=%organizationShortName%/cloud/%SYSID%/#, cloud/%SYSID%/#
port=1883
user_id=demo.meeting@azeti.net
password=demo.meeting
tls_enable=False
# take one on the following options:
# PROTOCOL_TLSv1
# PROTOCOL_TLSv1_1
# PROTOCOL_TLSv1_2
tls_version=PROTOCOL_TLSv1_1
mqtt_version=MQTTv311
external_broker_connected_sensor_id=cloud_connected
external_broker_severity_connected=0
external_broker_severity_offline_last_will=200
external_broker_severity_offline=100

[HD2CloudExporter]
destination_topic=hd/%SYSID%
# example publish interval definition: "05:20:25" -> HH:MM:SS
publish_first_publish_delay=00:00:05
publish_interval=00:05:00
publish_zipped=True
data_subscription_topic=calibrated_result/#
supress_identical_results_in_publish_interval=True

[persistord]
defaultPersistType=circular
defaultPersistParameter=300
persistFrequency=1
inMemory=True
dbPath=/opt/azeti/SiteController/persistent

[data_store]
# upload interval to server in seconds
upload_interval=60
# the maximum count of items (cal. results, events, ...)
# in one message to server
max_items_per_upload=100
# the maximum count of items (cal. results, events, ...)
# in the L1 cache (memory)
max_items_L1=3000
publish_zipped=True
# the minimum count of items to do zipping
limit_to_compress=5
dbPath=/opt/azeti/SiteController/persistent

[trapd]
external_interface=
trap_port=162

[ConfigProvider]
config_filename=sensor_config.xml
save_config_updates_to_disk=True
backup_config_count=3
backup_config_filename_suffix=_%Y%m%d_%H%M%S
# module_specific_log_level = INFO
# SC-373: obsolete: backup_xml_toprettyxml = True

[JobProcessor]
mqtt_inbound_sub_topic=cloud/%SYSID%/jobs/#
status_pub_topic=sys_msg/%SYSID%
job_folder=jobs
job_cfgFileName=job_config.xml

[remote_exec_calls]
# provide key=value pairs to define remote commands that could be executed on
# this system via a job called from the cloud
# (cloud sends the key, SC takes the command from the value provided by the
# key and executes the command)
# e.g. to open a vpn connection on cloud request, you could install a openvpn
# configuration in path_to/client.ovpn, prepare a set of all required
# certificates, use a line like the following one in here and start a simple
# job from the cloud providing the parameter "openvpn":
# openvpn = openvpn --config path_to/client.ovpn --daemon --log /tmp/openvpn.log

[CalibResultsEvaluator]
create_event_on_any_error_level=True
error_level_default_state=ERROR

[serial_line_daemon]
serial_interfaces=

[SiteController.conf]
start_cloud_modules=Yes
start_local_storage=No
start_simulator=No
sc_host_type=Ubuntu
log_destination=/opt/azeti/SiteController/log
tmp_destination=/tmp/SiteController
persist_destination=/opt/azeti/SiteController/persistent
config_folder=/opt/azeti/SiteController/config
mosquitto_folder=/usr/local
mosquitto_cfg_folder=/etc/mosquitto

[ModbusMaster]
mqtt_publishing_host=127.0.0.1
mqtt_publishing_client_id=
mqtt_publishing_ver=

mqtt_listening_host=127.0.0.1
mqtt_listening_client_id=ModbusMaster-listen
mqtt_listening_ver=MQTTv311

mqtt_publisher_is_equal_to_listener=True

serial_interfaces=/dev/ttyUSB0
max_error_count=5
logger=azeti_file
max_retry_sleep=10.0

[Watchdog]
mqtt_publishing_host=
mqtt_publishing_client_id=
mqtt_listening_host=127.0.0.1
mqtt_listening_client_id=Watchdog-listen
logger=azeti_file

[SrcUpdater]
backup_location=/tmp/SiteController/backups
logger=azeti_file

[simonsvoss]
logger=azeti_file
module_specific_log_level=INFO
reset_to_idle_timer_sec=5.0
reset_to_idle_uid_data_value=000000
reset_to_idle_card_data_value=000000
reset_to_idle_public_hid_value=0
reset_to_idle_pin_value=000000

[gps_tcp_client]
logger=azeti_file
module_specific_log_level=INFO

[loggers]
keys=root, azeti_file

[handlers]
keys=consoleHandler, fileHandler, TimedRotatingFileHandler, SizeRotatingFileHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler

[logger_azeti_file]
level=DEBUG
handlers=SizeRotatingFileHandler
qualname=azeti_file
propagate=0

[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)

[formatter_simpleFormatter]
format=%(asctime)s:%(process)d:[%(filename)s:%(lineno)s]:%(levelname)s:%(message)s
# %(asctime)s - %(name)s - %(levelname)s - %(message)s
# %(asctime)s:%(process)d:[%(pathname)s:%(lineno)s]:%(levelname)s:%(message)s
datefmt=

[handler_fileHandler]
class=FileHandler
#level=NOTSET
formatter=simpleFormatter
args=('%(logfilename)s',)

[handler_TimedRotatingFileHandler]
class=handlers.TimedRotatingFileHandler
#level=NOTSET
formatter=simpleFormatter
args=(['%(logfilename)s', 'MIDNIGHT', 1, 7])

# set to this value to use the system log level
# level=NOTSET

# Size based rotation
[handler_SizeRotatingFileHandler]
class=handlers.RotatingFileHandler
#level=NOTSET
formatter=simpleFormatter
# Rotate if a file exceeds 1049000 bytes (1 MiB) and keep 5 old files
args=(['%(logfilename)s', 'a', 10490000, 5])

General

In the general section of the configuration, it is possible to choose a name (serial) for the SiteController. This must be a unique name, since it is not possible to have two identical names in the Location List/Sites.

The timezone defined here only affects the timestamp in the log files. It does make sense to use the timezone of the administrator, for easier debugging.

[General]
# Allowed characters for the serial are upper and lower case ASCII [a-zA-Z],
# digits [0-9], dashes - and underlines _ only!
serial= azetiDemo # This is the unique name required for every SiteController.
listenOn=
mqtt_version=MQTTv311
timezone=Etc/UTC
# DO NOT CHANGE base_defaults_id MANUALLY!
base_defaults_id=8464a79
# server_sysconfig_revision is for server feedback purposes - has no impact on SC operation
server_sysconfig_revision=13

outbox_check_interval_seconds=30
outbox_persist_interval_seconds=60
outbox_confirm_published_timeout_seconds=600
dbPath=/opt/azeti/SiteController/persistent
default_logger=azeti_file

Broker

The broker section is for configuring the internal and external broker.

A Site Controller is in itself already a broker and subcribes by default to a couple of topics. In normal cases, there should be no need to change any of these.

If you are using the azeti Control Panel, then the host has to be defined here. As a customer you will receive at least one organization name from azeti. The Site Controller will need this information as a organizationShortName and needs to be inserterd accordingly.

Additionally the username and password is required. Please be aware, that the user needs broker privileges. These can be configured in the Control Panel in the User Management section.

Default port should be 1883 unless you are hosting your own Engine on premise and have changed it.

[InternalBroker]
host=127.0.0.1
sub_topics=events/#, hd/#, config_backup/#, sys_msg/#, imgdata/#, vs_data/+/backup

[ExternalBroker]
host= azetibroker02.azeti.net # Host where the Engine is running on.
reconnect_delay=1
reconnect_delay_max=300
reconnect_exponential_backoff=True
organizationShortName=azeti # This is the Organization the SiteController should connect to. If using the azeti cloud, then this is part of the received credentials.
sub_topics=%organizationShortName%/cloud/%SYSID%/#, cloud/%SYSID%/#
port=1883
user_id=user@azeti.net # Username for the connection to the cloud. If using the azeti cloud, then this is part of the received credentials.
password=password # Password for the connection to the cloud. If using the azeti cloud, then this is part of the received credentials.
tls_enable=False
# take one on the following options:
# PROTOCOL_TLSv1
# PROTOCOL_TLSv1_1
# PROTOCOL_TLSv1_2
tls_version=PROTOCOL_TLSv1_1
mqtt_version=MQTTv311
external_broker_connected_sensor_id=cloud_connected
external_broker_severity_connected=0
external_broker_severity_offline_last_will=200
external_broker_severity_offline=100

Data_Store

It is in charge of managing the connection between our internal MQTT broker and the external cloud broker. Here we have the possibility to change the upload interval, for which the SiteController automatically sends the data to the azeti Engine (or any other MQTT broker). This is very usefull for Sites which have a low bandwith or limited data volume.

[data_store]
# upload interval to server in seconds
upload_interval=60
# the maximum count of items (cal. results, events, ...)
# in one message to server
max_items_per_upload=100
# the maximum count of items (cal. results, events, ...)
# in the L1 cache (memory)
max_items_L1=3000
publish_zipped=True
# the minimum count of items to do zipping
limit_to_compress=5
dbPath=/opt/azeti/SiteController/persistent

Trapd

The module listens to traps sent to the Site Controller. It will receive the traps, filter them and send them to the corresponding gateway in the system. It will also send traps to the configured receivers.

For a complete documentation regarding this module, please refer to the SNMP Traps - trapd site.

[trapd]
external_interface=
trap_port=162

ConfigProvider

It receives the configuration XML file, parses it and when it is correct distributes it to the corresponding modules and saves it as the current configuration. It will store it as well in a file for future restarts of the system. There should normally be no manual interference in this section.

[ConfigProvider]
config_filename=sensor_config.xml
save_config_updates_to_disk=True
backup_config_count=3
backup_config_filename_suffix=_%Y%m%d_%H%M%S
# module_specific_log_level = INFO
# SC-373: obsolete: backup_xml_toprettyxml = True

JobProcessor

This module receives jobs from the cloud and executes them in the site controller. Typical jobs can be update and installation of modules, changes in configuration files, changes in access control lists, etc. Normally no manual interference is required here.

[JobProcessor]
mqtt_inbound_sub_topic=cloud/%SYSID%/jobs/#
status_pub_topic=sys_msg/%SYSID%
job_folder=jobs
job_cfgFileName=job_config.xml

Remote_Exce_Calls

The remote execution calls, allows the user to run pre-defined scripts on the operating system, the SiteController is running on.

[remote_exec_calls]
# provide key=value pairs to define remote commands that could be executed on
# this system via a job called from the cloud
# (cloud sends the key, SC takes the command from the value provided by the
# key and executes the command)
# e.g. to open a vpn connection on cloud request, you could install a openvpn
# configuration in path_to/client.ovpn, prepare a set of all required
# certificates, use a line like the following one in here and start a simple
# job from the cloud providing the parameter "openvpn":
# openvpn = openvpn --config path_to/client.ovpn --daemon --log /tmp/openvpn.log


SiteController.conf

SiteController.conf defines the installation folders of the different config and logging files, as well as the mosquitto database folder. It does make sense to store the log files on a different storage device, if for example the gateway where the SiteController ist running, only has an SD-card.

[SiteController.conf]
start_cloud_modules=Yes
start_local_storage=No
start_simulator=No
sc_host_type=Ubuntu
log_destination=/opt/azeti/SiteController/log
tmp_destination=/tmp/SiteController
persist_destination=/opt/azeti/SiteController/persistent
config_folder=/opt/azeti/SiteController/config
mosquitto_folder=/usr/local
mosquitto_cfg_folder=/etc/mosquitto

ModbusMaster

This section deals with all configurations regarding the Modbus devices. All serial devices are configured here as well as the possibility to define a different host as the MQTT publisher / listener.

[ModbusMaster]
mqtt_publishing_host=127.0.0.1
mqtt_publishing_client_id=
mqtt_publishing_ver=

mqtt_listening_host=127.0.0.1
mqtt_listening_client_id=ModbusMaster-listen
mqtt_listening_ver=MQTTv311

mqtt_publisher_is_equal_to_listener=True

serial_interfaces= /dev/ttyUSB0 # Configuration of the serial devices is done here.
max_error_count=5
logger=azeti_file
max_retry_sleep=10.0

Watchdog

The watchdog checks marked sensor gateways if they are providing data within regular intervals. Should no message be received until the configured time out is reached, the watchdog sends a raw_result with a special error code to the same topic it was listening for results.

[Watchdog]
mqtt_publishing_host=
mqtt_publishing_client_id=
mqtt_listening_host=127.0.0.1
mqtt_listening_client_id=Watchdog-listen
logger=azeti_file

Logger_Azeti_File

The Logger_Azeti_File section allows the user to switch between different layers of logging. More detailed information can be found under Logging.

[logger_azeti_file]
level=INFO # Possible entries are "INFO, WARNING, ERROR, CRITICAL, DEBUG".
handlers=SizeRotatingFileHandler
qualname=azeti_file
propagate=0