+- Add cross references to relevant parts of the documentation and external links (e.g., relevant papers or source of info)
+
+.. contents::
+ :local:
+
+
+Principles
+==========
+
+The main priorities for the design of the software implementation are
+
+#. providing a high-level, easy-to-use but safe interface for application developers;
+#. allowing the same application code to be used for *simulation* and *deployment*;
+#. realizing small-footprint software that can be deployed in resource-constrained embedded devices.
+
+The RoSA software framework, is implemented in C++.
+The language allows defining high-level but lightweight interfaces with flexibility in the realization.
+The framework heavily utilizes templates, template metaprogramming, and constant expressions to let the compiler generate optimized code.
+We also encode dynamically-relevant static information into a custom format so that RoSA supports message passing with flexibility and minimal resource need --- without the dynamic overhead of C++ RTTI.
+
+Performing message passing and data manipulation is decoupled from the agent interface.
+The implementation of the runtime system is easily switched behind the declarative definition of agent-based applications.
+Running an application in different modes (e.g., simulation and deployment) is a matter of static configuration.
+
+Simulation is the execution of the application on a computer with sensor and actuator agents associated to input and output streams, respectively.
+Those sensor and actuator agents may interface actual sensors and actuators with custom C++ code when deployed in an embedded device.
+
+Case studies have been dony in simulation; support for deployment requires further development effort to complete the corresponding runtime implementation.
+
+The framework is being coded in standard C++.
+The only exceptions are some OS-specific code snippets within debugging and simulation facilities.
+The software can readily be deployed to all devices that are supported by a modern C++ compiler.
+
+Software Modules
+================
+
+The software implementation consists of four main modules:
+
+`Support`
+ provides general debugging, logging, typing, and I/O facilities, which are used in other modules and application code.
+
+`Agent`
+ is a library of self-aware functionalities for defining agents in application code.
+
+`Core`
+ defines a minimal agent system with message passing capabilities and runtime system implementations.
+
+`Deluxe`
+ provides an interface that matches the RoSA Architecture and utilizes RoSA Core.
+
+
+The RoSA Deluxe interface wraps the general agent interface of RoSA Core.
+RoSA Deluxe agents are defined by functions that take their input messages as parameters and provide their output messages as return values.
+The implementation takes care of handling messages --- minimizing boilerplate in application code --- and may perform static and dynamic checks to ensure operating conditions.
+
+Agents and Agent Systems
+------------------------
+
+RoSA Core defines the means for agents to receive and send messages.
+Messages are statically-typed tuples of basic types.
+An agent is defined as a list of message handler functions.
+An incoming message is handled by the first handler that can take the message as actual parameter.
+The handler may generate output messages via RoSA API calls.
+
+RoSA Deluxe agents build on RoSA Core agents and provide a higher abstraction level by hiding message passing.
+
+Each agent is owned by a *system*.
+Systems can instantiate agents and provide the actual implementation for execution: channels --- for message passing --- and control --- for triggering data manipulation.
+
+RoSA Core allows message passing between arbitrary agents within a system.
+The RoSA Deluxe interface enforces a hierarchical structure with master-slave relations.
+
+
+A RoSA application is an agent system.
+The Deluxe module allows implementing a system as a set of agent definitions and declarative description of their connections.
+
+Execution Model
+---------------
+
+How an application (i.e., agent system) is executed depends on the system implementation.
+The implementation of the system --- channel and control facilities --- is decoupled from the definition of an application --- agents and their connections within a system.
+RoSA Core allows swapping the system implementation for any application as a configuration option or by changing one line of application code.
+
+The current system implementation is based on Models of Computations (MoCs).
+We use the untimed MoC and are prepared for the discrete-timed MoC when time aspects have to be represented.
+The concepts of the agent-based approach are easily mapped to the formal MoCs.
+
+=================== ===========
+Agent-based concept MoC concept
+=================== ===========
+Agent Process
+Channel Signal
+Message Event
+=================== ===========
+
+A RoSA agent system --- mapping to a process network --- can be analysed in the formal model.
+
+
+Building and Running Applications
+---------------------------------
+
+RoSA has a CMake build project, which allows using the framework in different development environments.
+The build project defines compile-time options to disable or tune features statically (e.g., logging, debugging, and tracing facilities).
+Disabling unnecessary features improves the efficiency of compiled framework code in particular uses.
+A RoSA application and framework modules are linked into one executable, which allows exploiting link-time optimization possibilities (optimizing framework code for application need, removing unused framework code, etc.).
+
+
+The RoSA runtime system is a thin layer between the self-aware application and the underlying system; still it fulfills important responsibilities.
+The runtime system initializes the application by instantiating an agent system, performs message passing, and triggers data manipulation in agents.
+I/O and monitoring features are also provided by RoSA.
+The application code is not bloated with system-level bookkeeping and developers can focus on details of self-awareness.
diff --git a/docs/index.rst b/docs/index.rst
index e42d88a..cf61d5a 100755
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,83 +1,86 @@
==================
The RoSA Framework
==================
.. contents::
:local:
Overview
========
The RoSA (Research on Self-Awareness) Framework is intended to be used as a tool
for experimenting and evaluating new ways of implementing self-aware
applications.
This documentation was generated for RoSA version |release| on |today|.
Documentation
=============
.. toctree::
:hidden:
- Changelog
+ Design
Use
Build
Dev
Issues
Release
Plan
CommandGuide/index
+:doc:`Design`
+ General overview of design principles and decisions.
+
:doc:`Use`
Describes how to create your own software based on RoSA.
:doc:`Build`
Describes how to build RoSA.
:doc:`Dev`
Provides basic information for developers on how to contribute to RoSA.
:doc:`Issues`
Known issues and things to do with the current implementation of RoSA.
:doc:`Release`
Describes for maintainers how to make a new release of RoSA.
:doc:`Plan`
Discusses future work and possible ways to develop RoSA.
:doc:`CommandGuide/index`
Documentation for RoSA applications and tools.
Changes
=======
Refer to :doc:`Changelog`.
.. _API_Documentation:
API Documentation
=================
For details of the provided interface, refer to our `API documentation`_.
.. _API documentation: ../doxygen/html/index.html
License
=======
RoSA is distributed under the terms and conditions of the