diff --git a/docs/Reference guides/Developer API.md b/docs/Reference guides/Developer API.md new file mode 100644 index 0000000..e683dec --- /dev/null +++ b/docs/Reference guides/Developer API.md @@ -0,0 +1,13 @@ + +# Developer API + +Here you can see the different data related to the developer API. + +# Reference data +The API documentation with every available endpoint is here. If you want to know how to authorize correctly before consuming the API go here. + +In order to connect correctly you'll need this data: + +- **Authentication Token URL**: https://auth.biotz.io/realms/biotz-platform/protocol/openid-connect/token +- **Client_id**: biotz-platform-programmatic-users +- **Scope**: openid diff --git a/docs/Reference guides/Glossary.md b/docs/Reference guides/Glossary.md new file mode 100644 index 0000000..a320641 --- /dev/null +++ b/docs/Reference guides/Glossary.md @@ -0,0 +1,26 @@ +**Device type**: Biotz allows managing multiple different devices from the same account. “Types” are a way of grouping those devices. + +**Device**: a device in Biotz corresponds to a single device in the physical world. There should be a one to one mapping between the IOT devices and the devices registered in Biotz. +‍ + +**Data ingestion flow**: a data ingestion flow is the process of receiving data from the devices and persisting it in the database. + +- Data ingestion message type: each device type can have multiple message types for data ingestion.That means that the devices of that type can send different types of messages to the platform. +- Data ingestion message type schema: each data ingestion message type can have multiple schemas. That means that the devices can send the same message type data in different formats/shapes. For example, different devices of the same type might be sending the same data in a slightly different format because they are running different firmware versions. Or the same device might change its data schema during its life cycle. +**Alarms**: + +- Alarm trigger: an alarm trigger is a rule that defines when an alarm should be triggered. The triggers are specific to data ingestion message type schemas because they depend on the data attributes. +- Alarm: an alarm is the result of an alarm trigger being triggered. The alarm is triggered for a specific device. +Dashboards: + +**Dashboard**: +- Panel:a dashboard can have one or more visualization/charts. Each of them is called a panel. +- Variable: device selector that is defined at the dashboard level. Panels can use variables to make the device being viewed changeable by the final user. + +**Firmware** + +**Event**: an event is something that happened within the Biotz platform and has been registered for tracking purposes. For example, when a user joins an organization an event is registered. The events can sometimes generate notifications for the users. + +
+ ![Glossary](/img/glossary.png) +
diff --git a/docs/Reference guides/MQTT broker.md b/docs/Reference guides/MQTT broker.md new file mode 100644 index 0000000..dd0b935 --- /dev/null +++ b/docs/Reference guides/MQTT broker.md @@ -0,0 +1,40 @@ +## Connection details +- Host: mqtts://broker.biotz.io +- Port: 8883 +- Transport: TLS +- MQTT version: v3.1.1 + +## Authentication +The authentication values are generated and provided when a new device is registered in the Biotz Platform. Each device uses its own credentials. + +- **Client id**: generated and provided when a device is registered. +- **Username**: generated and provided when a device is registered. +- **Password**: generated and provided when a device is registered. + +More information about device registration here. + +## Topics + +### Publish + +#### Data ingestion + +``` +biotz/1/0/CUSTOMER-ID/DEVICE-ID/publish/data/MESSAGE-TYPE-INTERNAL-NAME +``` +More information +### Subscribe + +#### Remote actioning:‍ + +``` +biotz/1/0/CUSTOMER-ID/DEVICE-ID/subscribe/action/ACTION-MESSAGE-TYPE-INTERNAL-NAME +``` +More information + +### Firmware updates: + +``` +biotz/1/0/CUSTOMER-ID/DEVICE-ID/subscribe/firmware/update +``` +More information \ No newline at end of file diff --git a/docs/Reference guides/Message-type Schema specification.md b/docs/Reference guides/Message-type Schema specification.md new file mode 100644 index 0000000..dbb9529 --- /dev/null +++ b/docs/Reference guides/Message-type Schema specification.md @@ -0,0 +1,29 @@ +his is the specification for the schema of a message-type. The users will have to specify a device-type, with one to many message-type. Each message-type will have one to many schemas. + +This schema is the structure of the data that the device will be sending in each communication with Biotz. The definition provided in the schema creation in the web application is the one used to validate the incoming data. Also, this will be used to structure the specific database schema for the data to be stored in a structured way. + +At the moment Biotz offers support to a subset of MessagePack data types that are compatible with JSON format. + +Supported data types: + +- Displayed in UI +- JSON +- MessagePack +- DB column type +
+ ![message-type-schema](/img/message-type-schema.png) +
+ +Additional information about some of the data types above: + +Collection of identical items: collection of more than one identical item. Being an item anything from an object/map/dictionary to singular element as a text, boolean, integer or decimal. + +Collection of unrelated items: collection of any kind of item, present just once. + +Object / Map / Dictionary: They are containers of the final properties, as the Collections-related type. In this case, we only expect key-value pairs as children elements that are like following: + +- Keys can only be of type \`String` (in order to give support for JSON serialization format). +- Values cannot be of type \`Collection of…\` or \`Object\` type, as we do not support nesting properties in that way. +Null values: we can handle them in any format to be transformed to \`nil` Clojure values. + +In order to parse MessagePack binary data to Clojure and the other way around, we can use this library. \ No newline at end of file diff --git a/docs/Reference guides/_category_.json b/docs/Reference guides/_category_.json new file mode 100644 index 0000000..985dc95 --- /dev/null +++ b/docs/Reference guides/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Reference guides", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/static/img/glossary.png b/static/img/glossary.png new file mode 100644 index 0000000..79d6dc8 Binary files /dev/null and b/static/img/glossary.png differ diff --git a/static/img/message-type-schema.png b/static/img/message-type-schema.png new file mode 100644 index 0000000..bcfdcbf Binary files /dev/null and b/static/img/message-type-schema.png differ