Merge pull request #435 from gathanase/documentation

Improve documentation

docs/source/distribution/Distribution.md

@@ -16,7 +16,7 @@ To launch the gateway simply follow these three steps:
 2. Extract this archive to the location from which you wish to run the gateway.
 3. Run the start.sh script
 
-A more detailed guide is available in the [worked examples](../examples/Download.md).
+See how to [install and start](../setup.md) sensiNact.
 
 ## The gateway architecture
 

docs/source/examples/Interacting.md

@@ -6,7 +6,7 @@ To start with you will need a runnable gateway configured with REST access. If y
 
 ## Listing and Introspecting the gateway
 
-Listing the providers present in the gateway is very simple. Assuming that you're using the configuration from [the previous example](Configuring.md) then issuing a GET request to `http://localhost:8082/sensinact/providers` will return something like:
+Listing the providers present in the gateway is very simple. Assuming that you're using the configuration from [the previous example](../quick-start/Northbound.md) then issuing a GET request to `http://localhost:8082/sensinact/providers` will return something like:
 
 ```json
 {

docs/source/examples/_index.md

@@ -5,7 +5,5 @@ The following examples will help you to quickly get started with the sensiNact g
 ```{toctree}
 :maxdepth: 2
 
-Download
-Configuring
 Interacting
 ```

docs/source/index.md

@@ -9,7 +9,12 @@ Eclipse sensiNact aims at managing IoT protocols and devices heterogeneity and p
 
 The project is licensed under the terms of the [Eclipse Public License - v 2.0](EPL-2.0.md).
 
-## Main concepts
+## Northbound and Southbound
+Eclipse sensiNact supports a wide variety of communication interfaces. There are 2 kinds of interfaces:
+* [Northbound](northbound/_index.md) interfaces allow users to interact with sensiNact.
+* [Southbound](southbound/_index.md) interfaces allow sensiNact to communicate with sensors and actuator devices.
+
+## Data model
 
 Eclipse sensiNact represents its data using the following model:
 
@@ -22,13 +27,13 @@ Eclipse sensiNact represents its data using the following model:
 
 The model is described more in detail in the [Data Model](./core/CoreModel.md){.clear-right} section.
 
-
 ## Getting Started
 
 The following examples will help you to quickly get started with the sensiNact gateway
 
-* [Downloading and Launching](examples/Download.md) - See how to download and start sensiNact
-* [Configuring and Querying](examples/Configuring.md) - See how to change sensiNact's configuration and access the REST interface
+* [Download and start](setup.md) sensiNact
+* [Add a northbound REST interface](quick-start/Northbound.md) and communicate with sensiNact via REST
+* [Add a southbound interface](quick-start/Southbound.md) for sensiNact to fetch data
 * [Interacting with a southbound device](examples/Interacting.md) - See how to read a device's data, change editable fields, and listen for updates.
 * Building your own Southbound Provider - TODO
 

docs/source/quick-start/Northbound.md

@@ -0,0 +1,110 @@
+# Add a northbound interface
+
+Now that you [downloaded and installed](../setup.md) sensiNact, you need to add a [northbound interface](../northbound/_index.md) for users to communicate with the sensiNact gateway.
+
+To achieve this we need to configure the [feature manager](../distribution/Launcher.md#configuring-the-feature-manager) to include the necessary feature(s).
+
+## The sensiNact configuration file
+
+The sensiNact configuration file format is described [in detail here](../distribution/Launcher.md#the-configuration-file), but the important facts are that:
+
+1. The configuration file lives in the `configuration` folder
+2. The configuration file is `JSON` and uses the OSGi<sup>®</sup> [Configuration Resource Format](https://docs.osgi.org/specification/osgi.cmpn/8.0.0/service.configurator.html#d0e132453)
+3. The configuration file is *live* and will be reloaded by the gateway whenever you save changes
+
+## Add a simple rest Northbound interface
+
+After you [downloaded and installed](../setup.md) sensiNact, the `configuration/configuration.json` file contains something similar to the following:
+
+```json
+{
+  ":configurator:resource-version": 1,
+  ":configurator:symbolic-name": "org.eclipse.sensinact.gateway.feature.northbound.rest.example",
+  ":configurator:version": "0.0.1",
+  "sensinact.launcher": {
+    "features": [
+      "core-feature"
+    ],
+    "repository": "repository",
+    "featureDir": "features"
+  }
+}
+```
+
+This defines the `sensinact.launcher` configuration dictionary with an array of `features` and the locations to search when installing bundles and features.
+
+We need to add the following features to install the REST northbound interface:
+
+1. `jakarta-servlet-whiteboard-feature` - A web container implementing the OSGi<sup>®</sup> servlet whiteboard
+2. `jakarta-rest-whiteboard-feature` - A Jakarta RESTful Web Services whiteboard which uses the servlet whiteboard
+3. `northbound-rest-feature` - The [northbound REST interface](../northbound/RestDataAccess.md) for Eclipse sensiNact.
+
+We will also configure the REST northbound interface with anonymous access and the local 8082 port.
+
+Update the `configuration/configuration.json` file to match:
+```json
+{
+  ":configurator:resource-version": 1,
+  ":configurator:symbolic-name": "org.eclipse.sensinact.gateway.feature.northbound.rest.example",
+  ":configurator:version": "0.0.1",
+  "sensinact.launcher": {
+    "features": [
+      "core-feature",
+      "jakarta-servlet-whiteboard-feature",
+      "jakarta-rest-whiteboard-feature",
+      "northbound-rest-feature"
+    ],
+    "repository": "repository",
+    "featureDir": "features"
+  },
+  "org.apache.felix.http": {
+    "org.osgi.service.http.port": 8082,
+    "org.apache.felix.http.name": "sensiNact"
+  },
+  "JakartarsServletWhiteboardRuntimeComponent": {
+    "osgi.jakartars.name": "sensiNact.rest"
+  },
+  "sensinact.session.manager": {
+    "auth.policy": "ALLOW_ALL"
+  },
+  "sensinact.northbound.rest": {
+    "allow.anonymous": true
+  }
+}
+```
+
+## Start sensiNact
+
+The configuration file is *live* and will be reloaded by the gateway whenever you save changes, so the gateway will automatically install and configure the new features.  Still, you may stop sensiNact and restart it:
+```bash
+./start.sh
+```
+
+## Test the Northbound REST API
+
+You may use your browser at `http://localhost:8082/sensinact/providers/sensiNact`, or use curl to query sensinact.
+```
+curl http://localhost:8082/sensinact/providers/sensiNact
+```
+
+Expected response
+```json
+{
+  "type": "DESCRIBE_PROVIDER",
+  "uri": "/sensiNact",
+  "statusCode": 200,
+  "response": {
+    "name": "sensiNact",
+    "services": [
+      "system",
+      "admin"
+    ]
+  }
+}
+```
+
+You may want to read the [documentation for the northbound REST interface](../northbound/RestDataAccess.md#available-endpoints), or a [guide to using the REST interface](../examples/Interacting.md).
+
+In the next section, you will [add a southbound interface](Southbound.md) to your sensiNact gateway.
+
+