Skip to content

Commit

Permalink
Some changes to this fields.
Browse files Browse the repository at this point in the history
  • Loading branch information
aitormurgu committed Feb 27, 2024
1 parent f42e794 commit ba5e83a
Show file tree
Hide file tree
Showing 4 changed files with 91 additions and 3 deletions.
3 changes: 2 additions & 1 deletion docs/Tutorials/Step 4 - Creating a device.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ From the **Device type** dropdown list select **My test device type**. Remember



Now, click on **Save**. By doing so, Biotz will register the new device in the platform and perform certain actions to create the credentials for your device. Once it is done, you will automatically download the device credentials file. In the credentials file you will have important and sensitive information about your device. Among other things it contains the username and password of your device that is required to interact with Biotz services. Even though this is a tutorial, bear in mind that the credentials file should be stored in a safe place and avoid sharing it over the network. With this information before sending data to Biotz we need to authenticate and get our token.
Now, click on **Save**. By doing so, Biotz will register the new device in the platform and perform certain actions to create the credentials for your device. Once it is done, you will automatically download the device credentials file. In the credentials file you will have important and sensitive information about your device. Among other things it contains the username and password of your device that is required to interact with Biotz services. Even though this is a tutorial, bear in mind that the credentials file should be stored in a safe place and avoid sharing it over the network. With this information before sending data to Biotz we need to <a href="http://localhost:3000/docs/Tutorials/Step%205%20-%20Authenticating%20%20a%20device/" target="_self">authenticate and get our token</a>.


10 changes: 8 additions & 2 deletions docs/Tutorials/Step 5 - Authenticating a device.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,16 @@ However in order to call the **http-forwarder** service you have to identify you
With that information you can craft an HTTP request for this simulation to get the token. In this tutorial, it is assumed you have some experience working the terminal. As said at the beginning of this tutorial, **HTTPie** and **cURL** tools will be used to provide examples for HTTP requests. Here is the request to retrieve the token using both tools (please make sure to adjust the request with your own credentials):


``jsx title="HTTPie"
```jsx title="HTTPie"
http --form POST \
https://auth.biotz.io/realms/biotz-platform/protocol/openid-connect/token \
username=~HTTP USER FROM CSV~ \
password=~PASSWORD FROM CSV~ \
grant_type=password \
client_id=biotz-platform-devices \
scope=openid

```
<br></br>

```jsx title="cURL"
curl --request POST \
Expand All @@ -30,3 +31,8 @@ curl --request POST \
--data-urlencode client_id=biotz-platform-devices \
--data-urlencode grant_type=password \
--data-urlencode scope=openid
```
<br></br>

This will return a response which contains the **id_token**. Copy its value and hold on to it as you will need it to <a href="http://localhost:3000/docs/Tutorials/Step%206%20-%20Sending%20a%20data%20ingestion%20request/" target="_self">send the data ingestion request</a>.
41 changes: 41 additions & 0 deletions docs/Tutorials/Step 6 - Sending a data ingestion request.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@

Now that you have a token from Biotz Identity Provider, it is time to send actual data to Biotz. In this tutorial, as said before, you will simulate a device sending data using the terminal. The approach is basically the same as to retrieve a token, just an HTTP request to the **http-forwarder** service. It will take your request and re-route it into a queue to be processed when the system is available.
<br></br>
For the request to be accepted by the **http-forwarder** it needs three things:
- The **id_token**.
- The message type **internal name** for your device. This should be **mytestmessag** if you have been following this tutorial.
- Request **payload**. This is your device’s data. The payload should have the shape/structure of the schema you defined previously. That means, an **Object** containing the keys **hum**, **temp** and **time**.

In this case the **Object** is an JSON object since the **mytestmessag** definition was configured with the **JSON** encoding.

<br></br>
Now, the request is very simple, you will send just a single sample of data (a single request in this case) to the platform. Here is an example using both HTTPie and cURL.

```jsx title="HTTPie"
http --auth-type bearer \
--auth ~YOUR ID_TOKEN~ \
POST https://ingestion-http.biotz.io/api/device/publish/data/mytestmessag \
hum=20.5 temp=25.6
```
<br></br>

```jsx title="cURL"
curl --header "Content-Type: application/json" \
--header "Authorization: Bearer ~YOUR ID_TOKEN~" \
--request POST \
--data '{"hum": 20.5, "temp": 25.6}' \
https://ingestion-http.biotz.io/api/device/publish/data/~INTERNAL NAME OF MESSAGE_TYPE~
```
<br></br>

The response should look like this:
```
{
"success?": true,
"details": {}
}
```

If that is the response you got, then the request was successful. Now your data should be available on the platform. To see that, in the next step you will create a dashboard to display your data.

40 changes: 40 additions & 0 deletions docs/Tutorials/Step 7 - Displaying the data.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
In order to display the data you will need to create a dashboard and a panel. A dashboard is a collection of panels. Each panel contains a specific query to display your data. You can also apply different customizations to the panel's appearance. However, the focus of this tutorial is to just display your newly ingested data. Bear in mind that the data you will display is a single point, if you have followed this tutorial. Displaying a single point is not very useful but the end goal is to learn how it works. So, later on when you create your real dashboard panels you have a good foundation to do so.

<br></br>

To create a new dashboard, from the sidebar, click on the **Dashboards** section. This will open the dashboards list. In the top right corner, click on **New dashboard**. Give it the name **My test dashboard** and the same value for **Description**.

<center><img src="/img/NewDashboard.png" alt="New Dashboard"></img></center>

Click on create and now you have a dashboard. The dashboard alone is not really useful, so let us create a panel in it. On the dashboard list, click on the dashboard name. This will lead you to the dashboard view. On the top right corner, click on **New panel**. This will open a dropdown with the panel type options you can choose. For the purpose of this tutorial, select **Time series**.

<br></br>

Once you are in the panel creation page you will see on the left the panel basic information form, such as **Name** and **Description**. Fill both fields with **My test panel** value. To the right, you will have the query builder. The query builder will allow you to define what the panel should display. Configure the query builder with the following settings:

**Query 1**

- **Name: Humidity Mean**
- **Select device: My test device**
- **Select message type: My test message type**
- **Select attribute: humidity**
- **Select aggregation method: Mean**

<center><img src="/img/Query1.png" width="800" height="261" alt="Query 1"></img></center>

You can also change the appearance of the panel but that is out of the scope for this tutorial. As you can see, you can also add more queries to the panel but in this tutorial we want to make it simple and go with just a single query.

<br></br>

Once you fill the query builder with the details above click on **Save**. This will create the panel and it should display a single data point in your.

<center><img src="/img/MyTestPanel.png" alt="My test panel"></img></center>

If it says “No data to show” please make sure the time filter, found in the top right toolbar, is set to a smaller time range, for example 30 minutes.

<center><img src="/img/TimeFilter.png" alt="Time Filter"></img></center>

If everything is correct, you should see the data point you just sent to the platform a few minutes ago.

**Congratulations!**

0 comments on commit ba5e83a

Please sign in to comment.