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 detailled 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.
Example Configuration File
The default directory to the SiteController.cfg is /opt/azeti/SiteController/foobar
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
Enclose parameters and paths into double brackets
{{here is some /path/foobar}}when typing and Confluence automatically applies the preformat style.
Right: Headings use Capitalization for Nouns and Important Information and Words 4+ Letters
Wrong: Headings use capitalization for nouns and important Information and words 4+ letters
Writing Instructions
Instructions are numbered lists and links in the software are bold with arrows (dash plus > becomes: → ):
- Open Components → Edit and set your new component name
- Choose Lorem Ipsum and do something
XML snippets go into a code bracket with type XML: {code:xml} (this will insert a code macro here) like this:
<here is some></here is some>
Screenshots
Screenshots use a Drop Shadow effect which can be accessed by Edit → Properties
Writing Best Practice
Check this one: http://www.userfocus.co.uk/articles/usermanuals.html
Next Steps
- Link to a further read
- Link to other articles
- and more links