Overview

We present here a short overview of the general automated services offered by our so-called "Universal Server", to introduce them to newcomers. These services are implemented by US-Main, which relies notably on US-Common.

The next level of information is to read the corresponding source files, which are intensely commented and generally straightforward.

The project repository is located here.

Layer Stack

From the highest level to the lowest, as summarised here, a software stack involving the Universal Server usually is like:

• the Universal Server services themselves (i.e. this US-Main layer)
• [optional] the Universal Webserver, i.e. US-Web (for web interaction)
• US-Common (for US base facilities)
• [optional] Ceylan-Mobile (for 3G connectivity, notably SMS sending, relying on the Gammu library)
• [optional] Ceylan-Seaplus (prerequisite of Ceylan-Mobile, for a bridge from Erlang to the C language)
• jsx (to parse JSON sensor outputs)
• Ceylan-Oceanic (for the support of home automation, through the integration of Enocean devices and actuators; relies on our fork of erlang-serial)
• Ceylan-Traces (for advanced runtime traces)
• Ceylan-WOOPER (for OOP)
• Ceylan-Myriad (as an Erlang toolbox)
• Erlang (for the compiler and runtime)
• GNU/Linux

The shorthand for Universal Server is us.

Facilities Provided by this US-Main Layer

These are mainly administration services.

% 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 } }.

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

$ 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}
                              ]}
                       ]}.

-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() ] }.

{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]}.

Configuring US-Main

The US-Main server is part of our "Universal Server" infrastructure, and as such relies on the base US-Common configuration settings.

So the base information of the user-specified us.config file, found in the US Configuration directory (possibly located in /etc/xdg/universal-server/ or ~/.config/universal-server/), will apply (see this example thereof).

Notably, in this file, a 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"}.

This US-Main configuration file concentrates the settings of all the services presented below, and the ones of US-Main itself; it is additionally used by the US-Main scripts, notably in order to start, stop, or monitor a designated US-Main server.

For operational use, we recommend to create a US-Main specific user (to be set in the us_username entry of one's us.config file), in order to compartmentalise the accesses to resources. For example, provided a us-srv group has already been created:

$ useradd --create-home --shell /bin/rssh -g us-srv main-srv

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. main-srv) running US-Main is able to interact with the 3G device (e.g. /dev/ttyUSB-my-3G-key).

So gpasswd -a main-srv uucp can be executed as root (and possibly main-srv may run newgrp uucp).

Installing US-Main: Current Stable Version & Download

As mentioned, the single mandatory prerequisite of the Universal Server is US-Common, which relies on Ceylan-Traces, which implies in turn Ceylan-WOOPER, then Ceylan-Myriad and Erlang.

We prefer using GNU/Linux, sticking to the latest stable release of Erlang (refer to the corresponding Myriad prerequisite section for more precise guidelines), and building the Universal Server from sources, thanks to GNU make.

The Universal Server master branch is meant to stick to the latest stable version: we try to ensure that this main line always stays functional (sorry for the pun). Evolutions are to take place in feature branches and to be merged only when ready.

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Myriad myriad
$ cd myriad && make all && cd ..

$ git clone https://github.com/Olivier-Boudeville/Ceylan-WOOPER wooper
$ cd wooper && make all && cd ..

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Traces traces
$ cd traces && make all && cd ..


# Possibly:
$ git clone https://github.com/Olivier-Boudeville/erlang-serial
$ cd erlang-serial && make && DESTDIR=. make install && cd ..

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Oceanic oceanic
$ cd oceanic && make all && cd ..


# Also possibly:
$ git clone https://github.com/Olivier-Boudeville/Ceylan-Seaplus seaplus
$ cd seaplus && make all && cd ..

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Mobile mobile
$ cd mobile && make all && cd ..


$ git clone https://github.com/Olivier-Boudeville/us-common
$ cd us-common && make all && cd ..

$ git clone https://github.com/Olivier-Boudeville/us-main
$ cd us-main && make all && cd ..

Launching US-Main

We recommend running US-Main thanks to a native build (rather than as a release), and using for that the start-us-main-native-build.sh script, either directly (for testing) or through systemd (for actual use).

In this last case, first a symbolic link pointing to this script shall be typically created in the /usr/local/bin directory of the host of interest. Then the server is to be triggered based on /etc/systemd/system/us-main-as-native-build.service (see us-main-as-native-build.service).

For example:

$ systemctl start us-main-as-native-build
$ journalctl --pager-end --unit=us-main-as-native-build.service
$ systemctl enable us-main-as-native-build

Then one may run monitor-us-main.sh to browse its traces live at any time.

Like notified in the start-up message:

-- Starting US-Main natively-built application as user 'stallone' (EPMD port: 4506)...
       Executing application us_main_app.beam as a service (second form)
Write pipe '/tmp/launch-erl-1103261.w' found, waiting 2 seconds to ensure start-up is successful indeed.

 **************************************************************
 ** Node 'us_main' ready and running as a daemon.
 ** Use 'to_erl /tmp/launch-erl-1103261' to connect to that node.
 ** (then type CTRL-D to exit without killing the node)
 **************************************************************
 (authbind success reported)

one may use to_erl to connect directly; just remember that exiting the interpreter as usual (CTRL-C twice) thus means killing that node; prefer CTRL-D (once).

For further information one may refer to the US-Main shell scripts, which cover various administration-related tasks (deploying, starting, monitoring, stopping an US-Main server).

Apparently, in some cases (not always), stopping the US-Main server (typically with systemctl stop us-main-as-native-build.service) will not unregister it from its EPMD, which will not be stopped either. As a consequence, any next launching of the US-Main server is bound to fail after a time-out, and the VM log file (e.g. /opt/universal-server/us_main-native/us_main/log/erlang.log.1) will confirm that a node with the same name (us_main) already exists (and thus prevents the new launch).

In this case, the best solution is to kill that lingering EPMD (e.g. epmd -port 4507 -kill) or, more brutally, to run the kill-us-main.sh script (it will kill both any US-Main and its EPMD) - and then to restart US-Main.

Monitoring US-Main

If using the default US-Main EPMD port, checking whether an instance is running is as simple as:

$ export ERL_EPMD_PORT=4507 ; epmd -names
epmd: up and running on port 4507 with data:
name us_main at port 50002

Then executing kill-us-main.sh will kill any live US-Main instance and unregister it from its EPMD (without killing any EPMD daemon).

Support

Bugs, questions, remarks, patches, requests for enhancements, etc. are to be reported to the project interface (typically issues) or directly at the email address mentioned at the beginning of this document.

Licence

The Universal Server is licensed by its author (Olivier Boudeville) under the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of this license, or (at your option) any later version.

This allows the use of the Universal Server code in a wide a variety of software projects, while still maintaining copyleft on this code, ensuring improvements are shared.

We hope indeed that enhancements will be back-contributed (e.g. thanks to merge requests), so that everyone will be able to benefit from them.

Credits

Many thanks to David Alberto for his kind sharing in terms of computation of latitude-based daylight durations (in French).

Please React!

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line! (for that, follow the Support guidelines).

Ending Word

Have fun with the Universal Server!