.. |br| raw:: html

   <br />
   
.. Links
.. |pluginlist| raw:: html

   <a href="https://foglamp.readthedocs.io/en/develop/foglamp_plugins.html">FogLAMP Plugins</a>
   
   
.. |quickstart| raw:: html

   <a href="https://foglamp.readthedocs.io/en/develop/quick_start/installing.html">Installing FogLAMP</a>

.. |building| raw:: html

   <a href="https://foglamp.readthedocs.io/en/develop/building_foglamp/building_foglamp.html#building-foglamp">Building FogLAMP</a>

*******
FogLAMP
*******

This is the FogLAMP project.

FogLAMP is an open source platform for the **Internet of Things**, and an essential component in **Fog Computing**. It uses a modular **microservices architecture** including sensor data collection, storage, processing and forwarding to historians, Enterprise systems and Cloud-based services. FogLAMP can run in highly available, stand alone, unattended environments that assume unreliable network connectivity.

FogLAMP also provides a means of buffering data coming from sensors and forwarding that data onto high level storage systems. It assumes the underlying network layer is not always connected or may not be reliable. Data from sensors may be stored within FogLAMP for a number of days before being purged from the FogLAMP storage. During this time it may be sent to one or more historians and also accessed via a REST API for use by *local* analytical applications.

FogLAMP has been designed to run in a Linux environment and makes use of Linux services.
|br| |br|

Architecture
============

FogLAMP is built using a microservices architecture for major component areas, these services consist of:

- a **Core service** responsible for the management of the other services, the external REST API's, scheduling and monitoring of activities.
- a **South service** responsible for the communication between FogLAMP and the sensors/actuators.
- a **Storage service** responsible for the persistence of configuration and metrics and the buffering of sensor data.

This core set of services may also be extended using optional services that are available within their own repositories, for example a notification service and a control dispatcher service.

FogLAMP makes extensive use of plugin components in order to increase the flexibility of the implementation:

- **South plugins** are used to allow for the easy expansion of FogLAMP to deal with new South devices and South device connection buses.
- **North plugins** are used to allow for connection to different historians
- **Datastore plugins** are used to allow FogLAMP to use different storage mechanisms for persisting meta data and the sensor data

The South and North plugins are stored in separate source code repositories which are named in the pattern foglamp-south-<device> foglamp-north-<service>. A complete list of plugins can be found in the readthedocs documentation for the project. See |pluginlist|.

The optional services, for example the notification service also make use of plugins to extend the capabilities of those services.

The other paradigm that is used extensively within FogLAMP is the idea of **scheduling processes** to perform specific operations. The FogLAMP core contains a scheduler which can execute processes based on time schedules or triggered by events. This is used to start processes when an event occurs, such as FogLAMP starting, or based on a time trigger.

Scheduled processes are used to send data from FogLAMP to the historian, to purge data from the FogLAMP data buffer, to gather statistics for historical analysis and perform backups of the FogLAMP environment.
|br| |br|

Pre-built packages for FogLAMP are available, see |quickstart| for details of how to use these.

Building FogLAMP
================

See also |building| in the online documentation.

Build Prerequisites
-------------------

FogLAMP is currently based on C/C++ and Python code. The packages needed to build and run FogLAMP may be installed by running the script *requirements.sh*


Linux distributions
-------------------

FogLAMP can be built or installed on the following Linux distributions, supporting both x86_64 and aarch64 architectures.

- Ubuntu 20.04, 22.04, 24.04
- Raspbian Bullseye, Bookworm

Install the prerequisites
-------------------------

The prerequisites required to build FogLAMP can be installed on any of the supported platforms by running the requirements.sh script from this directory.

.. code-block:: console

	sudo ./requirements.sh

.. note::

   This script will use the platforms package management software, such as apt on Ubuntu systems, to install the required packages. This must be done as the root user and hence the need to run requirements.sh using the sudo command
 
Build
-----

To build FogLAMP run the command ``make`` in the top level directory. This will compile all the components that need to be compiled and will also create a runable structure of the Python code components of FogLAMP.

**NOTE:**

- *The GCC compiler version 5.4 available in Ubuntu 16.04 LTS raises warnings. This is a known bug of the compiler and it can be ignored.*

- *openssl toolkit is a requirement if we want to use https based REST client and certificate based authentication.*

Once the *make* has completed you can decide to test FogLAMP from your development environment or you can install it. 
|br| |br|


Testing FogLAMP from Your Development Environment
=================================================

you can test FogLAMP directly from your Development Environment. All you need to do is to set one environment variable to be able to run FogLAMP from the development tree.
::
   export FOGLAMP_ROOT=<basedir>/FogLAMP

Where *basedir* is the base directory into which you cloned the FogLAMP repository.

Finally, start the FogLAMP core daemon:
::
   $FOGLAMP_ROOT/scripts/foglamp start

|br|

Installing FogLAMP
==================

Create an installation by executing ``make install``, then set the *FOGLAMP_ROOT* environment variable specifying the installation path. By default the installation will be placed in */usr/local/foglamp*. You may need to execute ``sudo make install`` to install FogLAMP where the current user does not have permissions:
::
   sudo make install
   export FOGLAMP_ROOT=/usr/local/foglamp

The destination may be overriden by setting the variable *DESTDIR* in the make command line, to a location in which you wish to install FogLAMP. For example, to install FogLAMP in the */opt* directory use the command:
::
   sudo make install DESTDIR=/opt
   export FOGLAMP_ROOT=/opt/usr/local/foglamp

|br|

Upgrading FogLAMP on Debian based systems
========================================

FogLAMP supports the Kerberos authentication starting from the version 1.7.1 and so the related packages are installed by the script `requirements.sh <requirements.sh>`_.
The *krb5-user* package prompt a question during the installation process asking for the KDC definition, the packages are installed setting the environment *DEBIAN_FRONTEND*
to avoid this interaction:
::

	# for Kerberos authentication, avoid interactive questions
	DEBIAN_FRONTEND=noninteractive apt install -yq krb5-user
	apt install -y libcurl4-openssl-dev

The upgrade of the FogLAMP package should follow the same philosophy, it should be done executing the command:
::
    sudo DEBIAN_FRONTEND=noninteractive apt -y upgrade

before the upgrade of FogLAMP, *SETENV:* should be set/added in */etc/sudoers.d/foglamp* to allow *sudo* to support the handling of the environment variables, a sample of the file:
::

    %sudo ALL=(ALL) NOPASSWD:SETENV: /usr/bin/apt -y update, /usr/bin/apt-get -y install foglamp, /usr/bin/apt -y install /usr/local/foglamp/data/plugins/foglamp*.deb, /usr/bin/apt list, /usr/bin/apt -y install foglamp*, /usr/bin/apt -y upgrade

|br|

Executing FogLAMP
=================

FogLAMP is now ready to start. Use the command:
::
   $FOGLAMP_ROOT/bin/foglamp start

To check if FogLAMP is running, use the command:
::
   $FOGLAMP_ROOT/bin/foglamp status

The command returns the status of FogLAMP on the machine it has been executed.


If You Use PostgreSQL: Creating the Database Repository
=======================================================

This version of FogLAMP relies on SQLite to run. SQLite is embedded into the Storage service, but you may want to use PostgreSQL as a buffer and metadata storage (refer to the documentation on `ReadTheDocs <https://foglamp.readthedocs.io/en/develop/building_foglamp/building_foglamp.html?highlight=appendix#appendix-setting-the-postgresql-database>`_ for more info. With a version of PostgreSQL installed via *apt-get* first you need to create a new database user with:
::
   sudo -u postgres createuser -d <user>

where *user* is the name of the Linux user that will run FogLAMP. The FogLAMP database user must have *createdb* privileges (i.e. the *-d* argument).
|br| |br|


Troubleshooting
===============

FogLAMP version 1.7.0
--------------------

$FOGLAMP_ROOT/data/etc directory ownership
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The execution of the *sudo make install* immediately after *git clone* will create a *data/etc* directory owned by the *root* user,
it should be owned by the user that will run FogLAMP, to fix it:
::
    chown -R <user>:<user> $FOGLAMP_ROOT/data

where *user* is the name of the Linux user that will run FogLAMP.
|br| |br|
