Presence Simulator

The goal is to give to any outside observer the illusion that a building is currently inhabited, for example by switching light(s) on and off as if actual people were busy in such a premise.

For that, US-Main will control an (Enocean) smart plug (itself able typically to toggle a well-chosen, low-consumption lamp visible from outside), based on intra-day logical presence slots. Such a slot is defined by two milestones, a start and a stop one (respectively to switch the smart plug on and off), which may be either a (fixed) intra-day time() (hence {Hour,Minute,Second}), or the dawn and dusk symbolic deadlines (atoms), which are then recomputed each day (based on the current date, and on the longitude and the latitude specified by the user for the location of the premise of interest).

The general principle, if the so-called "smart-lighting" feature is enabled, is to switch on a lamp during the busy hours of the day iff no natural light can be expected. All possible cases are expected to be covered (even, for extreme latitudes, days without dawn and/or dusk).

If smart lighting is not enabled, then during a slot of simulated presence, the actuator will be triggered unconditionally (that is whether daylight shall be expected or not).

By default, the following single intra-day logical presence slots, controlling a single set of actuators, are defined, for a simulated presence with smart lighting:

• from TMorningStart = 7:30 AM to TMorningStop = 8:30 AM, unless any dawn is to happen concurrently
• from TEveningStart = 6:30 PM to TEveningStop = 11:45 PM, unless any dusk is to happen concurrently

More generally, the user is free, through the presence_simulation_settings, either to select a default policy or to specify their own presence program (constant presence or absence, or a list of presence slots), with or without smart lighting.

For example, in one's US-Main configuration file of interest, possibly named foobar-us-main-for-production.config, as referenced in the us_main_config_filename key of us.config (both files being typically in /etc/xdg/universal-server) one may go for the default program:

% The EURID of any device (typically a push button or a double rocker)
% that serves to indicate whether someone is at home:
%
{ presence_switching_actuator, "004584A6" }.

% The settings in terms of presence simulation:
{ presence_simulation_settings, { default, undefined } }.

If a user-specific program is preferred, here with a single slot, with default source and target EURIDs, and with smart lighting:

{ presence_simulation_settings, [
 { presence_simulation_setting, undefined, undefined,
   [ { { 6, 30, 0 }, { 8, 0, 0 } }, { { 19, 30, 00 }, { 23, 30, 00 } } ], true } ] }.

Note that US-Main manages gracefully DST (Daylight saving time).

Alarm System

The principle is to monitor a set of (Enocean) sensors (typically opening detectors for doors, windows, etc.), and to report whenever a problem is detected.

The US-Main must be first told when the alarm system shall be active; this is typically when no one is at home, which can be notified to US-Main either by executing a script (e.g. leaving-home.sh, in charge also for example of locking all running computers) or by pushing an (Enocean) foot switch located at the front door. Then, after a configurable delay, the alarm system will be enabled.

All sensors are then monitored, any opening being reported.

Other events will be reported, whether or not the alarm system is active:

• when an undeclared sensor is first seen
• if a known sensor vanishes (e.g. it has been destroyed, or it ran out of power)
• if a jamming attempt is detected

When any abnormal event occurs, US-Main logs it and may typically sends to the user notifications, by SMS and/or by e-mail.

Preparing the Setup

The monitoring done by this server relies on the sensors executable (typically /usr/bin/sensors, obtained generally from a package of the same name and relying on lm-sensors). One may install the i2c-tools package as well for DIMM information (see R2 below).

The sensors-detect script must have been run once by root beforehand (select then only the default, safer options, by hitting Enter repeatedly or simply use its --auto option), in order to configure sensors.

Sensor configuration is typically stored in /etc/sensors3.conf, and must exist prior to running the US-Main server.

Mode of Operation of the Sensor Manager

Once the sensor manager is started, temperatures are periodically tracked (i.e. the currently reported one, plus minimum, maximum, and average since start) and compared to thresholds (any critical temperature as reported by the chips, and also ones set by our sensor manager itself in order to trigger alarms).

Abnormal temperatures (that is, going above - or even below - relevant thresholds) are then automatically timestamped and reported to the user by the US logic (i.e. notified in traces with appropriate severity, and possibly sent to the user thanks to emails and/or SMS, see the communication gateway service).

Similarly, any fan that would stop whereas not being PWM [1] is reported, and the same applies should an intrusion happen.

Many sensors report bogus values; the US Sensor Manager does its best to filter them out appropriately. This includes temperatures outside of any realistic ranges and an intrusion being reported right from US-Main startup (whereas, supposedly, it had not happened already).

$ ls -l /sys/class/hwmon/hwmon*/intrusion*
-rw-r--r-- 1 root root 4096 Jul 11 19:30 /sys/class/hwmon/hwmon3/intrusion0_alarm
-rw-r--r-- 1 root root 4096 Jul  8 21:46 /sys/class/hwmon/hwmon3/intrusion0_beep
-rw-r--r-- 1 root root 4096 Jul 11 19:30 /sys/class/hwmon/hwmon3/intrusion1_alarm
-rw-r--r-- 1 root root 4096 Jul  8 21:46 /sys/class/hwmon/hwmon3/intrusion1_beep
$ echo 0 >| /sys/class/hwmon/hwmon3/intrusion1_alarm
$ cat /sys/class/hwmon/hwmon3/intrusion1_alarm
1

{sensor_monitoring, [

   % Under that key shall be specified a list of
   % {sensor_id(), 'all_points' | [user_specified_point()]} pairs
   % in order to mute the sensors / measurement points that are known to be
   % bogus:
   %
   {muted_measurements, [
       {{nct6792, isa, "0a20"}, ["AUXTIN1"]},
       {{acpitz, acpi, "0"}, all_points}
                              ]}
                       ]}.

Contact File Format

Contact files are ETF files that contain a range of information about persons and organisations of interest.

Each non-commented line of these files shall be of the following format:

-type contact_line() :: { UserId :: user_id(),
   FirstName :: ustring(), LastName :: ustring(), NickName :: ustring(),
   Comment :: ustring(), BirthDate :: maybe( ustring() ),
   LandlineNumber :: maybe( ustring() ), MobileNumber :: maybe( ustring() ),
   PrimaryEmailAddress :: maybe( ustring() ),
   SecondaryEmailAddress :: maybe( ustring() ),
   PostalAddress :: maybe( ustring() ),
   Roles :: [ role() ] }.

A typical contact line could then be:

{1, "James", "Bond", "007", "MI6 Agent 007", {17,5,1971},
 "+44 9 81 47 25 40", "+44 6 26 83 37 22", "james.bond@mi6.uk.org",
 undefined, undefined, [administrator, secret_agent]}.

See also our test contact ETF file as a full example thereof.

Contact File Location

The path to a contact file can be either specified as an absolute one, or as a relative one - in which case it will be deemed relative to the US configuration directory.

They may be mere symlinks pointing to contact files kept in VCS in other locations.

Location of the US Configuration Files

The US configuration files will be searched through various filesystem locations [3] in turn:

• first in any directory designated by the XDG_CONFIG_HOME environment variable (default value: $HOME/.config)
• second in any of the directories listed in the XDG_CONFIG_DIRS environment variable (default: /etc/xdg;, directories being separated by :)

So the main, overall US configuration file, us.config, is found based on this series of directories that are gone through in an orderly manner; the first directory to host such a file becomes the (single) US configuration directory; let's name it US_CFG_ROOT.

This directory, in which generally all configuration files for a US-Main deployment lie is, with our conventions, typically either ~/.config/universal-server/ (in development mode), or /etc/xdg/universal-server/ (in production mode).

The other US-related configuration files (e.g. any us-main.config) are then referenced directly from the main one (us.config), and are designated from there through specific keys, here us_main_config_filename; the associate value may be either an absolute path, or one relative to the aforementioned US configuration directory (which is recommended).

US-Common Configuration

So the general, user-specified configuration file for US servers is named us.config, and the content of this example us.config should be pretty self-explanatory.

Note that, as US-Main supports an epmd_port entry in its own configuration file and has its own default port, such an entry should not be set in the general us.config file, as its value would not be taken into account anyway - it would just be misleading.

Setting User and Group

For operational use, we recommend to create at least a US specific user (to be set in the us_username entry of one's us.config file) - and possibly additionally a US-Main specific one, in order to better compartmentalise the accesses to the US-Main resources.

For example, provided that a US-specific group (named for instance us-group) has already been created (otherwise, do it with groupadd us-group), a us-main-user user can be defined, and made belonging to that group:

# Only sftp allowed if relying on a rssh (package available on the AUR) shell,
# or prefer just /bin/false:
#
$ useradd --create-home --shell /bin/rssh -g us-group us-main-user
# (if wanting to change afterwards: 'chsh --shell /bin/false us-main-user')

If having a regular user (e.g. named bond) who shall be also able to operate on US-Main deployments (e.g. to monitor their traces locally), it can be added to that group as well: usermod -a -G us-group bond (if this user is logged in, this will not be effective before the logout of this user or the user runs newgrp us-group).

Finally, the us.config US-Common configuration file and the US-Main one it references shall have the right user and group; for example:

$ chown us-main-user:us-group /etc/xdg/universal-server/*.config

Permissions of Configuration Files

Note that, as these files might contain sensitive information (e.g. Erlang cookies), they shall be duly protected and, in terms of permissions, we should have 640 for them.

So, supposing that the us.config designates, in its us_main_config_filename entry, foobar-us-main-for-production.config as the name of the US-Main configuration file [4], we could have:

-rw-r----- 1 us-user      us-group [...] us.config
-rw-r----- 1 us-main-user us-group [...] foobar-us-main-for-production.config

chmod and chown shall thus be used accordingly.

Finally, if being able to rely on multiple, different US configuration directories is necessary in order to be able to launch multiple US-Main instances (these configurations can then register the managers involved - typically the US-Main Configuration server - under different names), only a single node can be used per EPMD instance as, by default, such a node is named us_main (so two US-Main instances would then clash at this level).

As a consequence, in order to run multiple US-Main instances (e.g. one in production, one for testing) on a given host, they shall be multiplexed on different EPMD ports (see the epmd_port key of the US-Main configuration file; as a result, different universal-server configuration directories shall then be relied upon).

Specifying the US-Main Configuration File

In us.config , an us_main_config_filename entry can be specified in order to designate the US-Main configuration file that shall be used; for example:

{us_main_config_filename, "us-main-for-tests.config"}.

Test Configuration Files

Versions of the US and US-Main configuration files may be used for testing purposes and/or for examples.

For example, as root:

$ cd /etc/xdg/universal-server/
$ ln -s $US_COMMON_ROOT/priv/conf/us.config
$ ln -s $US_MAIN_ROOT/priv/conf/us-main-for-tests.config

Of course in the general case one will devise one's configuration files according to one's context and needs.

Specifying a US-Main Specific EPMD Port

For US-Main, the default EPMD port is 4507 (preferred to the default, more general US-level EPMD port, 4506).

This helps compartmentalising the nodes, and then US-Main (possibly including its EPMD daemon) can be restarted without affecting the other Erlang applications that may be running concurrently.

The user may specify an EPMD of their liking, providing it neither clashes nor is filtered by the local firewall. This can be done by specifying in the US-Main configuration file (instead of in us.config) an epmd_port entry.

For example:

{epmd_port, 4666}.

Communication Gateway

The communication gateway will rely on Ceylan-Mobile to send SMS. For that, a suitable 3G device (typically a USB key) will have to be used.

As mentioned in this section, proper permissions must apply, so that the user (e.g. us-main-user) running US-Main is able to interact with the 3G device (e.g. /dev/ttyUSB-my-3G-key).

So gpasswd -a us-main-user uucp can be executed as root (and possibly us-main-user may run newgrp uucp to update its group identification).