diff --git a/README.md b/README.md index 39fe01cc..fe127168 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# OpenSensorHub Docs +# OpenSensorHub Docs Documentation site for all things OpenSensorHub! diff --git a/docs/osh-node/quickstart/build-configuration.md b/docs/osh-node/quickstart/build-configuration.md index da0040f6..2cc997c8 100644 --- a/docs/osh-node/quickstart/build-configuration.md +++ b/docs/osh-node/quickstart/build-configuration.md @@ -5,29 +5,32 @@ sidebar_position: 5 # Configuring an OSH Node -The easiest way to modify the configurations in your project will be within an IDE. +This page guides you through how to customize your OSH Node. From adding specific drivers (sensors) and processes (interactions between data streams) to your OSH Node. This page will take you from your `osh-node-dev-template` folder, to a new OSH Node, that has been customized with desired drivers and processes. + +The easiest way to modify your Node, with configurations, is to do it within an IDE Some later guides may include workflow & project setup in **IntelliJ IDEA** (free version available) but other IDEs can be used as well. -Once you have cloned the project, open it in your IDE. +Once you have cloned the project , open `osh-node-dev-template` in your IDE. ## Including Modules in the Build -Within the project's root directory there will be a project wide `build.gradle` and `settings.gradle`. +Within the project's root directory there will be the files `build.gradle` and `settings.gradle` which makes changes project wide. + :::info In Java, the "root directory" typically refers to the base or top-level directory of a file system. In the `osh-node-dev-template`, the root directory contains subdirectories such as `dist`, `include`, `processing`, `sensors`, etc. ::: -To include modules into your build from `osh-addons`, `osh-core`, or a directory that you build yourself, you must modify both the `build.gradle` & `settings.gradle`. +To include modules into your build from `osh-addons` (drivers, sensors, processes, etc), `osh-core` (framework architecture), or a directory that you build yourself, you must modify both the `build.gradle` & `settings.gradle` files. ### settings.gradle The `settings.gradle` file is used to configure and define the subprojects of a multi-project Gradle build. -It's primarily responsible for defining which subprojects are included in the build and configuring project-level settings. +It's primarily responsible for defining which subprojects are included in the build and configuring project-level settings. -It controls which projects are part of the build, typically by including or excluding subprojects. +It is how Gradle knows what addons are being added to your Node, controlling which projects are part of the build, typically by including or excluding subprojects. OpenSensorHub uses `settings.gradle` to define subprojects that we either use in our build or to resolve dependencies of other subprojects. @@ -49,14 +52,18 @@ def toolsDir = "$rootDir/tools" Use these definitions to quickly reference the paths to the projects you need to implement. -An example of adding a subproject to our `settings.gradle`. This project will be available to your `build.gradle` and all subproject `build.gradle`s that are included in this build. +An example of adding a subproject to our `settings.gradle`. This project will be available to your `build.gradle` and all subprojects `build.gradle` that are included in this build. + ```gradle title="/osh-node-dev-template/settings.gradle" include '[module-name]' project(':[module-name]').projectDir = "$sensorDir/[path]/[module-name]" as File ``` -The module name is typically something like `sensorhub-driver-{name}` (for sensor drivers) or `sensorhub-process-{name}` (for processing modules) +The module name is typically something like `sensorhub-driver-{name}` (for sensor drivers) or `sensorhub-process-{name}` (for processing modules). + +Prebuild drivers and processes (subprojects) can be found in the include folder, which you can add to your Node through the above method in `settings.gradle` #### Adding all submodules in a directory + Toward the bottom of the page you will see a block of code: ``` gradle title="/osh-node-dev-template/settings.gradle" FileTree subprojects = fileTree("$rootDir/sensors").include('**/build.gradle') @@ -70,7 +77,8 @@ subprojects.files.each { File f -> } ``` -This code will include all subprojects from the `/osh-node-dev-template/sensors`. However, we can also use this method for including all submodules in a subdirectory. +The purpose of this code, it to tell build.gradle where to look in the file for your addons. This code above will include all subprojects from the `/osh-node-dev-template/sensors`. However, we can also use this method for including all submodules in a subdirectory (comms, dist, security, etc). + For example, using the `osh-addons` directory, we can include all sensors from `osh-addons` by referencing `"$sensorDir"` which includes modules from `/osh-node-dev-template/include/osh-addons/sensors` If you build your project within that directory it will automatically add your project's build.gradle to the build. @@ -94,6 +102,7 @@ subprojects.files.each { File f -> ``` ### build.gradle + The `build.gradle` file is the build script for a single project (either the root project or a subproject). It contains the logic for building the project, such as dependencies, plugins, tasks, and other build configurations. @@ -106,14 +115,40 @@ Open `build.gradle` in the root directory. The dependencies block is shown with some examples commented out. -Add a dependency for the driver you wish to add: +Add a dependency for the driver you wish to add, at the bottom of the dependencies nested block + +For a driver ```gradle title="/osh-node-dev-template/build.gradle" -implementation project(':sensorhub-driver-fakeweather') +implementation project(':sensorhub-driver-{name}') ``` + +For a process ```gradle title="/osh-node-dev-template/build.gradle" -implementation project(':sensorhub-process-geoloc') +implementation project(':sensorhub-process-{name}') ``` +### Example Workflow + +This workflow will show you how to add a driver to your OSH Node. + +The OSH-addons has several simulated datasets that one can add to their Node, to check that it is working (`include/osh-addons/sensors/simulated`). + +One of these simulated data sets is sensorhub-driver-fakeweather, which this guide will add to an OSH Node. + +First, open `settings.gradle` in the root directory. Under the definitions, add the following two lines + +```gradle title="/osh-node-dev-template/settings.gradle" +include 'sensorhub-driver-fakeweather' +project(':sensorhub-driver-fakeweather').projectDir = "$sensorDir/simulated/sensorhub-driver-fakeweather" as File +``` + +Then, open `build.gradle` in the root directory. In the nested block for dependencies, add at the bottom the following line of code + +```gradle title="/osh-node-dev-template/build.gradle" +implementation project(':sensorhub-driver-fakeweather') +``` + +Upon adding these dependencies to your `build.gradle`, your **OpenSensorHub** Node will have to be built again through your command line. Navigate to your `osh-node-dev-template` directory and repeat the steps to build an OSH Node. Then your Node will be build with these drivers/processes/modules installed and ready to run. -Upon adding these dependencies to your `build.gradle`, your **OpenSensorHub** node will build with these drivers/processes/modules installed and ready to run. \ No newline at end of file +*User Documentation* will explain how to use and deploy these addons. \ No newline at end of file diff --git a/docs/osh-node/quickstart/build.md b/docs/osh-node/quickstart/build.md index 79c9cdd7..48c76755 100644 --- a/docs/osh-node/quickstart/build.md +++ b/docs/osh-node/quickstart/build.md @@ -3,14 +3,15 @@ title: Build sidebar_position: 3 --- + # How to Build an OSH Node -This page guides you through building an OSH Node from source using the command line. +This page guides you through how to build your OSH Node in your command line. Starting from your requirements and ending with a zip file housing the architecture to build your own customizable OSH Node. ## Getting the Code The `git` command is used to download the code from the GitHub repositories hosting **OpenSensorHub**. -For example, you can download the code for an OSH Node Development Template using the following command: +You can download the code for an OSH Node Development Template, using the HTTPS with the following command: ```git git clone --recursive https://github.com/opensensorhub/osh-node-dev-template.git @@ -21,7 +22,7 @@ The `--recursive` flag is required because the repository contains submodules. ::: ## Building from the Command Line -You can the build the code from source using Gradle on the command line. +You can build the Node, using Gradle, on the command line. Change into the directory where you cloned the repository: @@ -39,7 +40,7 @@ distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-bin.zip distri... ``` ::: -To build, run the following: +To build your local OSH node, enter the following: ```sh ./gradlew build -x test ``` @@ -47,7 +48,10 @@ To build, run the following: `-x test` excludes unit tests from the build process ::: +This will result in a build of your OSH node, formed in a zip file. Later steps will help you unzip the file and begin running your OSH node + +Finally, locate the file, by opening build then distributions to find your file. -The result OSH node will build in: +Path:`/osh-node-dev-template/build/distributions/osh-node-..*.zip` -`/osh-node-dev-template/build/distributions/osh-node-..*.zip` +Titled: `osh-node-..*.zip` \ No newline at end of file diff --git a/docs/osh-node/quickstart/deploying.md b/docs/osh-node/quickstart/deploying.md index 3972d4b9..6f175363 100644 --- a/docs/osh-node/quickstart/deploying.md +++ b/docs/osh-node/quickstart/deploying.md @@ -5,13 +5,17 @@ sidebar_position: 4 # Deploying an OSH Node +This page guides you through how to run your OSH Node, locally on your computer. Starting from your OSH Node zip file and ending with your Node running on your browser. + ## Basic Deployment -After building the node, you can navigate to the newly generated ``` /osh-node-dev-template/build/distributions``` directory. +After building the node, you can navigate to the newly generated ``` /osh-node-dev-template/build/distributions``` directory, moving from the build to the distributions folder. You will see the `osh-node-..*.zip` -Unzip the node. Within the extracted folder execute the launch script for your corresponding OS by either double-clicking or running the script in the command line: +To unzip the node, use the command `unzip osh-node-..*.zip`, when you are in the same directory that houses your zip file. + +To launch the script, change directories to the new unzipped folder, then execute the launch script for your corresponding OS by either double-clicking or running the script in the command line: :::note **Windows**: @@ -27,11 +31,7 @@ Unzip the node. Within the extracted folder execute the launch script for your c To test that the OSH server is running, you can visit [`http://localhost:8181/sensorhub/test`](http://localhost:8181/sensorhub/test), or by visiting the Admin UI. -Open your web browser and navigate to [`http://localhost:8181/sensorhub/admin`](http://localhost:8181/sensorhub/admin) - - -### Default OSH Configuration -With the deployment package, there is a `config.json` file containing a default configuration of **OpenSensorHub**. Within this configuration, only default users and service modules are configured. +To use your OSH Node, open your web browser and navigate to [`http://localhost:8181/sensorhub/admin`](http://localhost:8181/sensorhub/admin) :::info The default administrative credentials are: @@ -43,10 +43,23 @@ The default administrative credentials are: Below is an example of what you should see in the **OpenSensorHub** Admin UI. -We will cover using/deploying the different modules under *User Documentation*, with API reference available in the *Developer Documentation*. - ![OSH Admin User Interface](../../assets/osh/adminui/adminui.PNG) + +### Default OSH Configuration + +Within your OSH Node folder, there is a `config.json` file containing a default configuration of **OpenSensorHub**. Within this configuration, only default users and service modules are configured. + +Customizable settings will be covered in other sections. With using/deploying the different modules under *User Documentation* and API reference available in the *Developer Documentation*. + +### Ending and Restarting OSH Node + +Once your OSH Node folder has been created, you can end and restart your node from your command line. + +To restart your OSH Node, navigate to the same place that housed your zip file, and change directory to the unzipped folder. From there, enter the same launch script you used earlier. + +To end the node, just enter `Ctrl/Cmd + C` and the script will end along with your Node, needing you to restart it with the instructions above. Any saved configurations you have entered will be present when you start your node again. + ## Docker Deployment TBD \ No newline at end of file diff --git a/docs/osh-node/quickstart/now-what.md b/docs/osh-node/quickstart/now-what.md index d130c111..d626a9ee 100644 --- a/docs/osh-node/quickstart/now-what.md +++ b/docs/osh-node/quickstart/now-what.md @@ -3,14 +3,13 @@ title: Now What? sidebar_position: 6 --- -Once you know how to build and launch an **OpenSensorHub** node, -you can use it for a wide variety of use cases. +Once you know how to build and launch an **OpenSensorHub** Node, you can use it for a wide variety of custom archetypes. From using prebuild or custom sensors to processes for data collection, to any other case you can imagine. -Use **OpenSensorHub** as: +The possibilities are **endless**! + +Example uses of **OpenSensorHub** are: - commercial IoT management/data platform - common operating picture (COP) backend for tactical exercises - personal home security backend - a way to control a fleet of robots, UAVs, etc. -- a network of sensors/actuators with autonomous communication between OSH nodes - -The possibilities are **endless**! \ No newline at end of file +- a network of sensors/actuators with autonomous communication between OSH nodes \ No newline at end of file diff --git a/docs/osh-node/quickstart/requirements.md b/docs/osh-node/quickstart/requirements.md index 7a1f8530..b5319bce 100644 --- a/docs/osh-node/quickstart/requirements.md +++ b/docs/osh-node/quickstart/requirements.md @@ -1,17 +1,18 @@ --- title: Requirements sidebar_position: 2 ---- +--- -:::tip -It may be helpful to learn more about the core architecture of **OpenSensorHub** before getting started. +:::tip It may be helpful to learn more about the core architecture of **OpenSensorHub** before getting started. Please see the [Concepts & Architecture Section](../architecture/overview.md) if you're interested to learn more! ::: In order to build and run an **OpenSensorHub** node, you must have the following installed: -- Java 17+ -- Gradle 7.3+ +- Java 17 (Download [here](https://www.oracle.com/java/technologies/downloads/#java17)) + - Only runs on Java 17 + +- Gradle 7.3+ (Download [here](https://gradle.org/releases/?_gl=1*k0jrxt*_gcl_au*MjA3NjI5NzE0NS4xNzgyNzc1OTY4*_ga*MTE2MjM5Njg0NC4xNzgyNzc1OTY5*_ga_7W7NC6YNPT*czE3ODI3NzU5NjgkbzEkZzEkdDE3ODI3NzU5ODckajQxJGwwJGgw)) - Git **OpenSensorHub** is widely available for the following platforms: