|
1 | 1 | # swe-android |
2 | 2 |
|
3 | 3 | [](https://jitpack.io/#sofwerx/swe-android) |
| 4 | + |
| 5 | +A quick way to send sensor data to an OGC Sensor Observation Service - Transaction (SOS-T) server. |
| 6 | + |
| 7 | +## Table of Contents |
| 8 | +1. [Quick Start](#quick-start) |
| 9 | + 1. Gradle |
| 10 | + 1. Maven |
| 11 | +1. [What is SOS-T](#what-is) |
| 12 | +1. [How SOS-T Works](#brief-sos) |
| 13 | +1. [How to Send Sensor Data](#how-to) |
| 14 | + |
| 15 | +<h2 id="quick-start">Quick Start</h2> |
| 16 | + |
| 17 | +### Gradle Setup |
| 18 | + |
| 19 | +```gradle |
| 20 | +repositories { |
| 21 | + maven { url 'https://jitpack.io' } |
| 22 | +} |
| 23 | +
|
| 24 | +dependencies { |
| 25 | + implementation 'com.github.sofwerx:swe-android:1.0' |
| 26 | +} |
| 27 | +``` |
| 28 | + |
| 29 | +### Maven Setup |
| 30 | + |
| 31 | +```xml |
| 32 | +<!-- <repositories> section of pom.xml --> |
| 33 | +<repository> |
| 34 | + <id>jitpack.io</id> |
| 35 | + <url>https://jitpack.io</url> |
| 36 | +</repository> |
| 37 | + |
| 38 | +<!-- <dependencies> section of pom.xml --> |
| 39 | +<dependency> |
| 40 | + <groupId>com.github.sofwerx</groupId> |
| 41 | + <artifactId>swe-android</artifactId> |
| 42 | + <version>1.0</version> |
| 43 | +</dependency> |
| 44 | +``` |
| 45 | + |
| 46 | +<br/> |
| 47 | + |
| 48 | +<h2 id="what-is">What is SOS-T?</h2> |
| 49 | +The [**Open Geospatial Consortium***](https://www.opengeospatial.org/) is a group committed to making open standards for the geospatial community. One of those standards is the [**Sensor Observation Service**](https://www.opengeospatial.org/standards/sos) which defines how sensors can be managed and share their data. SOS-T is a specific capability that many SOS servers possess and is this library's focus. While powerful and flexible, SOS and SOS-T standards are sometimes difficult to begin using. This library is an effort to make all those standards and nuanced data formats happen in the background leaving you to focus on the app you're building and the great data it has to share with the world. |
| 50 | + |
| 51 | +<h2 id="brief-sos">A Brief Overview of how SOS-T works</h2> |
| 52 | +An **SOS-T server** and a **Sensor** have a specific pattern of interaction. This pattern is as follows:<br/> |
| 53 | +1. The first time a **Sensor** wants to start providing data to a **SOS-T server**, the **Sensor** sends a message that describes itself. The **SOS-T server**, in response, sends back some identification names that the **SOS-T server** wants the **Sensor** to use to identify itself.<br/> |
| 54 | +2. When the **Sensor** is ready to tell the **SOS-T server** about the data the **Sensor** will provide, the **Sensor** sends the **SOS-T server** a template that describes its data. The **SOS-T server** relies back with an indentification name that the **SOS-T server** would like the **Sensor** to use to label its data so the **SOS-T server** can match that data back to the **Sensor**.<br/> |
| 55 | +3. Up until this point, the **Sensor** and **SOS-T server** have just negotiated descriptions and data formats, no sensor readings have actually gone from the **Sensor** to the **SOS-T server**. These two set-up steps only need to be done once.<br/> |
| 56 | +4. Now, when the **Sensor** wants to send data, it just sends a short form with its data and the label that the **SOS-T server** provided earlier. If all goes well, the **SOS-T server** lets the **Sensor** know that the data was received in a short reply. The **Sensor** keeps repeating this step whenever it wants to send new data. |
| 57 | + |
| 58 | +<h2 id="how-to">How to Send Sensor Data</h2> |
| 59 | +To use this library, you should have some type of sensor in an app that needs to send data to an SOS-T server. This library started as a way to connect the SOFWERX [**TORGI**](https://github.com/sofwerx/TORGI) app to an SOS-T and is a good example of the library at work. This library is **not** the definitive answer on how to connect every sensor scenario with an SOS-T server, but it helped the TORGI effort and it's offered in hopes it will help other sensor developers as well. You can see the specific implementation of this library in the [**Torgi Service**](https://github.com/sofwerx/TORGI/blob/master/torgi/src/main/java/org/sofwerx/torgi/service/TorgiService.java). <br/><br/> |
| 60 | + |
| 61 | +###Step 1: build your sensor |
| 62 | +You can build a sensor by providing a human-readable name that uniquely identifies this one particular sensor, a unique ID for this sensor, a title for this type of sensor, and a human-readable description of the sensor. |
| 63 | +```java |
| 64 | +SosSensor sosSensor = new SosSensor("Sensor 18742","sensor18742","TORGI","Tactical Observation of RF and GNSS Interference sensor"); |
| 65 | +``` |
| 66 | +<br/> |
| 67 | +Next you want to add SensorMeasurements to your sensor, SensorMeasurements describe what the sensor measures. For our example, our sensor measures the amount of "foo" at a particular time and location like this: |
| 68 | +```java |
| 69 | +sosMeasurementFoo = new SensorMeasurement(new SensorResultTemplateField("foo","www.your_link_that_describes_the_foo_standard.com","foo per inches")); //the url provided in the second field helps others understand about this idea of "foo" if you dont have a link, you can provide some placeholder or a way to contact you |
| 70 | +sosMeasurementTime = new SensorMeasurementTime(); |
| 71 | +sosMeasurementLocation = new SensorMeasurementLocation(); |
| 72 | +sosSensor.addMeasurement(sosMeasurementFoo); |
| 73 | +sosSensor.addMeasurement(sosMeasurementTime); |
| 74 | +sosSensor.addMeasurement(sosMeasurementLocation); |
| 75 | +``` |
| 76 | +###Step 2: describe the SOS-T server |
| 77 | +Now you need to tell the library about where the sensor should send its data |
| 78 | +```java |
| 79 | +SosService sosService = new SosService(context, sosSensor,"www.your-sos-t-server.com", true, true); |
| 80 | +``` |
| 81 | +Those last two boolean values deserve a bit more attention. The first, *turnOn* means that if set to true, the library will immediately try to contact the **SOS-T server** and handle all the initial information about what the **Sensor** intends to provide.<br/> |
| 82 | +The second boolean, *enableIpcBroadcast* means that the library will send out your sensor data to other apps on your same device. This is included primarily to support a future link with [**OpenSensorHub-Android**](https://github.com/opensensorhub/osh-android). If you want to send your sensor data to other apps on the same device, but not out over the internet to an SOS-T server, just provide *null* for the sosServerURL. |
| 83 | +###Step 3: send your data |
| 84 | +When you have something to report to the **SOS-T server**, you can update the data in your SensorMeasurements |
| 85 | +```java |
| 86 | +sosMeasurementTime.setValue(System.currentTimeMillis()); |
| 87 | +sosMeasurementLocation.setLocation(latitude,longitude,altitude); |
| 88 | +sosMeasurementRisk.setValue(foo); |
| 89 | +``` |
| 90 | +and then send that data off to the **SOS-T server** |
| 91 | +```java |
| 92 | +sosService.broadcastSensorReadings(); |
| 93 | +``` |
| 94 | +<br/> |
| 95 | +You can repeat this step as often as needed. There is no requirement to handle the connection with the server. The library runs on another thread and will make the connection whenever is needed and pass and receive information automatically. |
| 96 | + |
| 97 | +###Step 4: disconnecting |
| 98 | +When you are finally done communicating with the server, clean up the server connection by calling: |
| 99 | +```java |
| 100 | +sosService.shutdown(); |
| 101 | +``` |
0 commit comments