Skip to content

Commit

Permalink
Finishing with the text
Browse files Browse the repository at this point in the history
  • Loading branch information
aitormurgu committed Feb 28, 2024
1 parent b32678b commit 837ddee
Show file tree
Hide file tree
Showing 10 changed files with 121 additions and 4 deletions.
54 changes: 54 additions & 0 deletions docs/How-to guides/How to create developer API credentials.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
To create applications that consume our data we have a Developer API, following <a href="https://[en.wikipedia.org/wiki/Universally_unique_identifier](https://api.test.biotz.io/docs/ui/index.html#/)" target="_self">this link</a> you will be able to consult more information about the endpoints in our documentation.

## Credentials creation

In order to connect with the API, you need to create some **credentials** in the credentials view, under the **Developer API** section

<div class="tutorial-image-container">
![credentials creation](/img/credentials-creation.png)
</div>


Once here, clicking in the **New credentials** button will redirect you to the form. In this view we have to set the credentials name, a description can also be set to differentiate better between one another.
<div class="tutorial-image-container">
![new credentials](/img/new-credentials.png)
</div>
<br></br>

When finished, click **Save** and it will show the user information:
<div class="tutorial-image-container">
![credentials created succesfully](/img/credentials-created-succesfully.png)
</div>
As shown in the pop-up, this information will only appear once. So download the credentials file and save somewhere safe.

## API consumption

Now that we have our credentials created. We need to configure the authentication. For this example we will use the API documentation mentioned before.
<div class="tutorial-image-container">
![developer](/img/biotz-developer-api.png)
</div>
Clicking the **Authorize** button a pop-up will show, in which we need to add this information, also found on the Developer API Reference:

- **Username:** The username in the credentials file we have downloaded before.
- **Password:** The password in the credentials file we have downloaded before.
- **Client credentials location:** You need to set this to Authorization header.
- **Client_id:** You need to set always "biotz-platform-programmatic-users".
- **Client_secret:** This one goes empty.
- **Scopes:** You need to check the openid box.

<div class="tutorial-image-container">
![authorize1](/img/authorize1.png)
</div>
When the authorization is done correctly, you should see a pop-up saying that your **Authorized**.

<div class="tutorial-image-container">
![authorize2](/img/authorize2.png)
</div>
With this your capable of consuming the API and get the needed data.







Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
## Introduction
The communication debugger has as objective to help debug possible errors or problems related to the communication coming from the devices into Biotz Platform.

## Prerequisites
There must be these things defined at Biotz: device-type, message-type and schema. And at least a device registered for the defined device-type.

Also the device firmware must be ready to connect to Biotz and send data.

## Communication debugger
The communication debugger will monitorize the communications that are sent to Biotz application coming from a certain device and for a certain message-type. This provides a way to check if the messages supposedly

The tools is available under 'Developer Tools' menu item. Once selected, two inputs are shown:

- Select device: in here the device from which the communication has to be debugged must be selected.
- Select message type: The selected device, will be of a certain device type and could have more than one message type registered for it. Each message type can be debugged on its own.

Once those are selected communication debugger can be started by using the 'Start session' button. This will show a 'terminal' style view where all communications from the device published in the selected message-type topic. The communications shown are all of them, as these aren't filtered by schema matching.

At the bottom right three buttons are shown:

- Stop: to pause the 'terminal' style view of showing more communications. That can be latter re-started.
- Download: to download all the communication in a json format into the local machine.
- Cancel: to shut down the communication debugger.
40 changes: 40 additions & 0 deletions docs/How-to guides/How to update device firmware.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
Biotz offers a remote firmware update service. The user will upload the new firmware file to the Biotz IoT platform where it will be registered and stored. From that point on the user will be able to assign any firmware file to existing devices.

For this to be possible, the device must be subscribed to the MQTT topic where Biotz will publish the firmware update message. The topic name follows this format:

```
biotz/1/0/CUSTOMER-ID/DEVICE-ID/subscribe/firmware/update
```

In the topic name format there are two elements that have to be personalized:

- **CUSTOMER-ID**: Is shared by all devices of the organization. It is provided when a device is registered in the web application, and it has a <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier" target="_self">UUID</a> format.
- **DEVICE-ID**: Is specific to each device. It is provided when a device is registered in the web application, and it has a <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier" target="_self">UUID</a> format.

There are specific security measures in place for these topics. The devices can just subscribe to them, publishing is not allowed.

Whenever the user assigns a certain firmware file to a device (or a set of devices), a message will be published to the specific topic(s) just described. This message will be published with the MQTT Retained flag set to true. This means that the MQTT broker will keep the message around, and **every time** the device connects to the MQTT broker and subscribes to the topic, the message will be delivered to the device. Thus, the device must be ready to deal with repeated firmware update messages in a sensible way (e.g., by recognizing that the firmware name specified in the message is the same already running on the device, and not doing any updates).

The reason why the firmware update message is sent with the MQTT Retained flag set to true is twofold:

- The device can know that there is a firmware update pending, even if it was disconnected from the MQTT broker at the time the message was sent.
- Biotz IoT Platform can assign firmware updates to devices even before those devices connect to the MQTT broker for the first time.

The payload of the MQTT message is a UTF-8 encoded string, that holds a JSON object with the following content:

```
{
"firmware-name": "firmware name",
"download-url": "https://firmware-download-url"
}
```

The download URL has an expiration period of **one week**. After that time the URL will no longer be valid.

To summarize:

- The device must be subscribed to specific topic to get the message(s),
- It must decode the UTF-8 encoded string to build the JSON object,
- It must check the "firmware-name" key and decide if it has to apply the update or not,
- If it does decide to apply the update, it must download the firmware file from the URL specified in the "download-url" key,
- Once it has downloaded the firmware file locally, it may perform some checks to verify the suitableness of the firmware file (integrity checks, authenticity checks, compatibility checks, etc.), and then perform the auto-update.
8 changes: 4 additions & 4 deletions src/css/custom.css
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@

/* You can override the default Infima variables here. */
:root {
--ifm-color-primary: #2e8555;
--ifm-color-primary-dark: #29784c;
--ifm-color-primary-darker: #277148;
--ifm-color-primary-darkest: #205d3b;
--ifm-color-primary: #00E1FD;
--ifm-color-primary-dark: #FFBE0C;
--ifm-color-primary-darker: #5133FF;
--ifm-color-primary-darkest: #140F38;
--ifm-color-primary-light: #33925d;
--ifm-color-primary-lighter: #359962;
--ifm-color-primary-lightest: #3cad6e;
Expand Down
Binary file added static/img/authorize1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/authorize2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/biotz-developer-api.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/credentials-created-succesfully.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/credentials-creation.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/new-credentials.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 837ddee

Please sign in to comment.