Add an example of configuring the gateway

Configure the Northbound REST interface and demonstrate that it can be used

Signed-off-by: Tim Ward <timothyjward@apache.org>

docs/distribution/Distribution.md

@@ -16,6 +16,8 @@ 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).
+
 ## The gateway architecture
 
 The gateway architecture is modular, and uses [OSGi](https://www.osgi.org)<sup>®</sup> as a platform. The gateway includes a launcher based upon the Feature service, which can deploy groups of bundles as a single unit.

docs/distribution/Launcher.md

@@ -153,8 +153,8 @@ An example file follows:
 ```js
     {
       ":configurator:resource-version": 1,
-      ":configurator:symbolic-name": "org.eclipse.sensinact.gateway.feature.jakartaservlet.test",
-      ":configurator:version": "0.0.1",
+      ":configurator:symbolic-name": "org.eclipse.sensinact.gateway",
+      ":configurator:version": "0.0.2-SNAPSHOT",
       "sensinact.launcher": {
         "features": [
           "jakarta-servlet-whiteboard-feature",

docs/examples/Configuring.md

@@ -0,0 +1,74 @@
+# Configuring sensiNact
+
+In order to configure sensiNact you will need to have a launchable gateway. If you haven't already got one then [this example](Downloading.md) will tell you how to obtain one.
+
+## 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
+
+## Adding a Northbound interface
+
+[Northbound interfaces](../northbound/Northbound.md) are externally facing components that allow users or machines to interact with the gateway. To add one we need to configure the [feature manager](../distribution/Launcher.md#configuring-the-feature-manager) to include the necessary feature(s)
+
+A clean gateway instance will start with a `configuration.json` containing something similar to the following:
+
+```js
+"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.
+
+Adding the sensiNact REST interface requires us to install three new features:
+
+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.
+
+These features are added as entries in the `features` array of the `sensinact.launcher` configuration.
+
+We can also configure these features to control the port used, and to enable anonymous access for the REST API. The exact configuration properties are defined by the implementations used in the features, for example the Apache Felix Http Jetty bundle in the `jakarta-servlet-whiteboard-feature`.
+
+The updated configuration will look something like this:
+
+```js
+"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",
+  "osgi.http.whiteboard.target": "(org.apache.felix.http.name=sensiNact)"
+},
+"sensinact.northbound.rest": {
+  "allow.anonymous": true,
+  "osgi.jakartars.whiteboard.target": "(osgi.jakartars.name=sensiNact.rest)"
+}
+```
+
+## Accessing the Northbound REST API
+
+Once the configuration is updated and saved the gateway will automatically install and configure the defined list of features. You can verify this by querying `http://localhost:8082/sensinact` in your browser, or from the command line by using a tool such as `curl`.
+
+    curl http://localhost:8082/sensinact
+
+The full set of endpoints available is listed in the [documentation for the northbound REST interface](../northbound/RestDataAccess.md#available-endpoints)

docs/examples/Download.md

@@ -12,7 +12,7 @@ Eclipse sensiNact is published to the Eclipse Nexus repository instance at [http
 ## Installing sensiNact
 
 Once you have obtained the sensiNact assembly you can unzip it using your favourite zip tool
- 
+
      unzip sensinact.zip
 
 The unzipped contents will include several folders and files including:
@@ -22,12 +22,14 @@ The unzipped contents will include several folders and files including:
 * `launch` - the folder containing the sensiNact launcher responsible for bootstrapping the gateway
 * `repository` - a maven layout repository containing the bundles used by the gateway features
 * `start.sh` - a launch script for sensiNact
- 
+
 ## Starting sensiNact
 
 Starting sensiNact can be achieved simply by executing the start script
 
     ./start.sh
 
 > [!WARNING]
-> If you are unable to execute the start script try setting the executable permission bit using `chmod +x start.sh`
+> If you are unable to execute the start script try setting the executable permission bit using `chmod +x start.sh`
+
+Once you have started sensiNact you should see some logs written to the console indicating that the gateway is running. In order to interact with the gateway you will need to [configure a northbound provider](Configuring.md)