3. Configure the DMS3 Components

All DMS³ components are configured through an associated text-based configuration file called a TOML (Tom's Obvious, Minimal Language) file with a common file extension *.toml. These files are very minimal in format, and well-documented with many defaults preset, so should be generally self-explanatory.

The table below associates the DMS³ package/component with the relevant TOML file:

Package/Component	TOML File Location
DMS3Server	dms3_release/config/dms3server/dms3server.toml
DMS3Client	dms3_release/config/dms3client/dms3client.toml
DMS3Libs	dms3_release/config/dms3libs/dms3libs.toml
DMS3Dashboard	dms3_release/config/dms3dashboard/dms3dashboard.toml
DMS3Mail	dms3_release/config/dms3mail/dms3mail.toml
DMS3Build	dms3_release/config/dms3build/dms3build.toml

3a. DMS³Server & DMS³Client Configurations

For both DMS³Server and DMS³Client components, configuration files must first be edited before getting redistributed across the end user network (optionally using the dms3build executable compiled in the previous step).

While DMS³Server and DMS³Client components have their own configuration file--dms3server.toml and dms3client.toml, respectively--they also share two additional configuration files from the DMS³Dashboard and DMS³Libs components, so be sure to edit these configuration files as well.

Edit the DMS³Server Configuration File (dms3server.toml)

By default, this file is installed into /etc/distributed-motion-s3/dms3server on the server, used for setting the following:

Table.Key Name	Description	Default Value
Server.Port	Port on which to run the DMS3Server	49300
Server.CheckInterval	The interval (in seconds) between checks for any change to motion state	15
Server.EnableDashboard	Enables (true) or disables (false) the DMS3Dashboard running over HTTP on this server	true
Audio.Enable	Enables (true) or disables (false) the play-back of audio on motion detector application start/stop	true
Audio.PlayMotionStart	The audio file played when the motion detector application is activated. Ignored if Audio.Enable == false	"" (empty string), which gets set to the path of the release /media folder and filename (e.g., /etc/distributed-motion-s3/dms3server/media/motion_start.wav). Any other filepath/filename will be used if valid, else set to local development folder
Audio.PlayMotionEnd	The audio file played when the motion detector application is deactivated. Ignored if Audio.Enable == false	"" (empty string), which gets set to the path of the release /media folder and filename (e.g., /etc/distributed-motion-s3/dms3server/media/motion_stop.wav). Any other filepath/filename will be used if valid, else set to local development folder
AlwaysOn.Enable	Enables (true) or disables (false) the motion detector application "Always On" feature which starts/stops detection based on time-of-day instead of the absence/presence of user proxy device(s) (e.g., smartphones)	true
AlwaysOn.TimeRange	The start and end times (24-hour format) for motion sensing to always be enabled, regardless of absence/presence of user proxy device(s). Ignored if AlwaysOn.Enable == false	["2300", "0400"]
UserProxy.IPBase	The first three address octets defining the LAN (e.g., 10.10.10.) where user proxies (devices representing users on the network, such as a smartphone) will be scanned for to determine when motion should be run	"10.10.10."
UserProxy.IPRange	The fourth address octet defined as a range (e.g., 100..254) in which to search for user proxies	[100, 254]
UserProxy.MacsToFind	The MAC addresses (e.g., "24:da:9b:0d:53:8f") of user proxy device(s) to search for on the LAN	["24:da:9b:0d:53:8f", "f8:cf:c5:d2:bb:9e"]
Logging.LogLevel	Sets the log levels for application logging using the following table. Note that DEBUG > INFO > FATAL, so DEBUG includes all log levels	2
	0 - OFF, no logging
	1 - FATAL, report fatal events
	2 - INFO, report informational events
	4 - DEBUG, report debugging events
Logging.LogDevice	Determines to what device logging should be set using the following table. Ignored if LogLevel == 0	0
	0 - STDOUT (terminal)
	1 - log file
Logging.LogFilename	Filename of the DMS3Server log. Ignored if LogLevel == 0 or LogDevice == 0	"dms3server.log"
Logging.LogLocation	Location of logfile (absolute path; must have full r/w permissions). Ignored if LogLevel == 0 or LogDevice == 0	"/var/log/dms3"

Edit the DMS³Client Configuration File (dms3client.toml)

By default, this file is installed into /etc/distributed-motion-s3/dms3client on each Smart Device Client (SDC) and used for configuring the following:

Table.Key Name	Description	Default Value
Server.IP	The address on which the DMS3Server is running	"10.10.10.9"
Server.Port	The port on which the DMS3Server is running	49300
Server.CheckInterval	The interval (in seconds) for checking with the DMS3Server	15
Logging.LogLevel	Sets the log levels for application logging using the following table. Note that DEBUG > INFO > FATAL, so DEBUG includes all log levels	2
	0 - OFF, no logging
	1 - FATAL, report fatal events
	2 - INFO, report informational events
	4 - DEBUG, report debugging events
Logging.LogDevice	Determines to what device logging should be set using the following table. Ignored if LogLevel == 0	0
	0 - STDOUT (terminal)
	1 - log file
Logging.LogFilename	Filename of the DMS3Client log. Ignored if LogLevel == 0 or LogDevice == 0	"dms3client.log"
Logging.LogLocation	Location of logfile (absolute path; must have full r/w permissions). Ignored if LogLevel == 0 or LogDevice == 0	"/var/log/dms3"

3b. DMS³Dashboard Configuration

Shared between both DMS³Client and DMS³Server, this file is installed into /etc/distributed-motion-s3/dms3dashboard on both the server and each participating device client.

Edit the DMS³Dashboard Configuration File (dms3dashboard.toml)

By default, this file is installed into /etc/distributed-motion-s3/dms3dashboard on the server and client devices, used for setting the following:

Table.Key Name	Description	Default Value
Server.Port	The port on which to run the DMS3Dashboard server	8081
Server.Filename	Filename of DMS3Dashboard HTML dashboard template file	"dms3dashboard.html"
Server.FileLocation	Location of the HTML dashboard template file. If empty, it uses the release dashboard folder. Any valid filepath/filename can be used.	"" (empty string)
Server.Title	Title of the DMS3Dashboard	"DMS3 Dashboard"
Server.ReSort	Enables (true) or disables (false) alphabetical re-sorting of devices displayed in the dashboard template	true
Server.ServerFirst	Enables (true) or disables (false) to make DMS3Server the first device displayed in the dashboard template. Ignored if ReSort == false	true
Server.DeviceStatus	Device status identifies the stages when a device is no longer reporting status updates to the dashboard server. Device status values are defined as a multiplier of Server.CheckInterval (default = 15 seconds) declared/defined in the dms3server.toml file. If the device check interval for the dashboard server is every 15 seconds (default), and the device status multiplier for caution (DeviceStatus.Caution) is 200 (default), then the dashboard server will report a device caution status (yellow device icon) after 3000 seconds (50 minutes) of no status updates received from that device. Device status will continue to progress through each of the stages identified below, or reset to a normal device status if device again reports in to the dashboard server
Server.DeviceStatus.Caution	Device status multiplier for caution. Represents the time before the device is marked as caution (yellow icon) in the dashboard, based on Server.CheckInterval	200
Server.DeviceStatus.Danger	Device status multiplier for danger. Represents the time before the device is marked as danger (red icon) in the dashboard	3000
Server.DeviceStatus.Missing	Device status multiplier for missing. Represents the time before a device is removed from the dashboard if no updates are received.	28800
Client.ImagesFolder	Location where the motion detection application stores motion-triggered image/movie files on the client	"/home/richbl/motion_pics"

3c. DMS³Libs Configuration

By default, shared by all DMS³ components, this file is installed into /etc/distributed-motion-s3/dms3libs on both server and participating device clients, and used to configure the location of system-level commands (e.g., ping).

Edit the DMS³Libs Configuration File (dms3libs.toml)

This file maps command name to absolute pathname, as follows:

Table.Key Name	Description	Default Value
SysCommands.APLAY	Location of the aplay system command used for audio playback	"/usr/bin/aplay"
SysCommands.BASH	Location of the bash system command used for executing bash scripts	"/usr/bin/bash"
SysCommands.CAT	Location of the cat system command used for concatenating and displaying file contents	"/usr/bin/cat"
SysCommands.ENV	Location of the env system command used for running commands in a modified environment	"/usr/bin/env"
SysCommands.GREP	Location of the grep system command used for searching text using patterns	"/usr/bin/grep"
SysCommands.IP	Location of the ip system command used for network configuration	"/usr/sbin/ip"
SysCommands.PGREP	Location of the pgrep system command used for searching for processes based on name or other criteria	"/usr/bin/pgrep"
SysCommands.PING	Location of the ping system command used for testing network connectivity	"/usr/bin/ping"
SysCommands.PKILL	Location of the pkill system command used for terminating processes based on name or other criteria	"/usr/bin/pkill"
SysCommands.MOTION	Location of the motion system command used for motion detection	"/usr/local/bin/motion"

Configuration of the Motion Application

The Motion application--used as the default motion detection application in DMS³--is configured differently based on the version of Motion installed on the client, and the client OS in use. When in doubt, consult the Motion documentation.

As an example, Motion 4.7.x running on a Raspberry Pi with the Bookworm (or later) operating system requires special configuration and the command to start Motion is libcamerify motion. Thus the SysCommands.MOTION key is set to the following:

MOTION = "/usr/bin/libcamerify motion"

In the configuration below, the Motion application is used, and in a recent release (0.2.2), the command to include its configuration file is required when running the dms3client as a system service:

MOTION = "/usr/local/bin/motion -c /usr/local/etc/motion/motion.conf"

Alternatively, in the above case when running a system service, the dms3client.service file can instead be edited to specify the Motion configuration folder:

[Service]
 Type=simple
 Restart=on-failure
 ExecStart=/usr/local/bin/dms3client
 ...
 WorkingDirectory=/usr/local/etc/motion
 ...

In this latter case, the following command is used to set the SysCommands.MOTION key (no need to specify the configuration folder):

MOTION = "/usr/local/bin/motion"

3d. Optional: DMS³Mail Configuration

DMS³Mail is a stand-alone client-side component responsible for generating and sending an email whenever a valid motion event is triggered in the Motion application.

Edit the DMS³Mail Configuration File (dms3mail.toml)

By default, this file is installed into /etc/distributed-motion-s3/dms3mail on each participating device client running the DMS³Client component, and used for setting the following:

Table.Key Name	Description	Default Value
Filename	Filename of the HTML email template file	"dms3mail.html"
FileLocation	The location of the HTML email template file. By default, the value is "" (empty string), which sets the path to the release email folder (e.g., /etc/distributed-motion-s3/dms3mail).	"" (empty string)
Email.From	Email sender	"dms3mail@businesslearninginc.com"
Email.To	Email recipient	"user@gmail.com"
SMTP.Address	Host of the SMTP server	"smtp.gmail.com"
SMTP.Port	Port of the SMTP server	587
SMTP.Username	Username to use to authenticate to the SMTP server	"user"
SMTP.Password	Password to use to authenticate to the SMTP server	"password"
Logging.LogLevel	Sets the log levels for application logging using the following table. Note that DEBUG > INFO > FATAL, so DEBUG includes all log levels	1
	0 - OFF, no logging
	1 - FATAL, report fatal events
	2 - INFO, report informational events
	4 - DEBUG, report debugging events
Logging.LogDevice	Determines to what device logging should be set using the following table. Ignored if LogLevel == 0	0
	0 - STDOUT (terminal)
	1 - log file
Logging.LogFilename	Filename of the DMS3Mail log. Ignored if LogLevel == 0 or LogDevice == 0	"dms3mail.log"
Logging.LogLocation	Location of logfile (absolute path; must have full r/w permissions). Ignored if LogLevel == 0 or LogDevice == 0	"/var/log/dms3"

3e. Optional: DMS³Build Configuration

The DMS³Build package is used to configure and redistribute DMS³ components to all participating hardware devices across the end user network. This process is automated using the dms3build executable compiled in the preceding step, and relies on its own configuration file, dms3build.toml, located at dms3_release/config/dms3build/dms3build.toml.

Edit the DMS³Build Configuration File (dms3build.toml)

This configuration file is broken into two separate sections, [Clients] and [Servers], and then further subdivided into sections for each of the hardware devices onto which DMS³ components will be installed.

For the [Clients] section, a sub-section needs to be completed for each of (n) participating hardware device(s). These sub-sections are numbered sequentially (e.g., [Clients.0], [Clients.1]... [Clients.n]). The table below shows just one such sub-section ([Clients.0]).

Table.Key Name	Description	Default Value
Clients.0.User	Username of the client device	"pi"
Clients.0.DeviceName	Domain name of the client device	"picam-alpha.local"
Clients.0.SSHPassword	SSH password for the client device (empty if using SSH certificate)	"" (empty string)
Clients.0.RemoteAdminPassword	Remote administration password for the client device (required for component installation)	"PASSWORD"
Clients.0.Port	SSH port of the client device	22
Clients.0.Platform	Platform of the client device. dms3build will use this to copy over the correct binary executable	"linuxArm7"

For the [Servers] section, a sub-section needs to be completed for each hardware device acting as a DMS³ server. As of this release, only one active DMS³ server has been tested.

Table.Key Name	Description	Default Value
Servers.0.User	Username of the server device	"richbl"
Servers.0.DeviceName	Domain name of the server device	"main.local"
Servers.0.SSHPassword	SSH password for the server device (empty if using SSH certificate)	"" (empty string)
Servers.0.RemoteAdminPassword	Remote administration password for the server device (required for component installation)	"PASSWORD"
Servers.0.Port	SSH port of the server device	22
Servers.0.Platform	Platform of the server device. dms3build will use this to copy over the correct binary executable	"linuxAMD64"