Physical devices must be authenticated and authorized to connect to the BlackBerry IoT Platform.
The BlackBerry IoT Platform allows data, files, and messages to be shared between devices in a secure manner. The data coming from devices (potentially millions) is immense. A device is represented on the BlackBerry IoT Platform as a device entity. There are other entities that represent things that are useful for organizing and managing devices. On the BlackBerry IoT Platform, all entities are identified by a universally unique identifier (UUID). Here an example of a UUID:
Above is the hierarchy entities on the platform. All entities are represented by boxes, with the exception of tag entities. Tag entities are different because they can be later applied to other entities and are represented differently. Solid lines indicate that an entity can belong to another entity and a dotted line indicates an association. Knowing this hierarchy is important for understanding how different entities relate to each other and how to best use capabilities.
There are different entities that you should be familiar with as they're the basis of understanding how to work with the BlackBerry IoT Platform. These entities include:
- organizations (orgs): An organization entity (or simply organization) is a representation of a group, company, or your physical organization on the BlackBerry IoT Platform.
- applications (apps): An application entity (or simply application) is a representation of the application code that runs on a physical device.
- devices: A device entity (or simply device) represents a single instance of application code running on a physical device.
- users: A user entity (or simply user) represents a person with a valid BlackBerry IoT Platform account.
- firehoses: A Firehose entity (or simply firehoses) allows for the streaming of event data from multiple devices to a common point that accessible for other devices.
- tags: A tag entity (or simply tags) represents a grouping of capabilities.
Another important part of working with the BlackBerry IoT Platform is understanding how to manage the security for the data. All data stored for the devices is secured using permission controls called capabilities. For more information about securing access to data, see Extended capabilities.
An organization entity (or simply organization) is a representation of a group, company, or your physical organization on the BlackBerry IoT Platform. Organization entities are useful for logically grouping various devices and applications together. If you put your devices into separate organizations, those devices can still be configured to share data, share files, or send messages.
Before you can create application entities, you require an organization. You can create your own organization entity or use an existing organization. Creators of an organization entity automatically have administrator privileges. You can choose to create multiple organizations to administer different companies or groups. If you're not a member of an existing organization, you can request that the administrator add you to the organization so that you can work with that organization (i.e., create application entities).
You can choose to configure your organization entity to restrict certain capabilities. Other entities, such as applications, belong to an organization and inherit any capabilities that are granted to the organization. For more information about capabilities, see Working with Capabilities and Tags.
Within an organization, you can create the following entities:
- firehoses, which represent a mechanism for devices to stream event data to a common location
- applications, which represent the application code that connects to the platform
- tags, which are used to group capabilities and help to simplify permission management
- devices, instances of applications
The following illustration provides an overview of the entities that you can create and add to an organization, that includes applications, firehoses, and tags. You don't actually create user entities, but simply add existing user entities to an organization. In a strict sense, users are associated with an organization and don't actually belong to an organization.
A user entity (or simply user) represents a person with a valid BlackBerry IoT Platform account. A user entity is created when a person activates their BlackBerry IoT Platform account. A person who creates an account must activate the account first before they can log in to the BlackBerry IoT Platform. A user can be added to multiple organizations.
Other entities can grant capabilitities to user entities. The application code running on a physical device can request to inherit the capabilities of the user logging in to the platform. When a person logs into an account, the corresponding user entity becomes associated with the device entity that they log in to. There can be only one user entity associated with one device entity at any given time. For more information about how capabilities inherited from the user logged in to the device, see Understanding user-based authentication.
An application entity (or simply application) is a representation of the application code that runs on the device. You can think of device entities as a type of application entity. Application code can run on embedded devices, servers, large data analytics servers, management consoles, smart phones, web browsers, etc.–basically anything that can connect to the Internet and can run code using any one of the BlackBerry IoT Platform SDKs. Instances of that code connect to the platform and each new instance is represented as a device entity. A device entity is created automatically the first time an instance of code connects to the platform when using user-based authentication. For device-based authentication, devices entities are created as part of a provisioning step before the physical device connects. For information about user-based and device-based authentication, see Understanding authentication.
The following illustration illustrates applications on the platform:
An API KEY and API SECRET are generated when an application entity is created. The API KEY and API SECRET are used to identify your application when it connects to the BlackBerry IoT Platform. Both the key and secret must be included in your application code; otherwise, the device won't be able to connect. For information about how to see the API KEY and API SECRET, see View application security.
For more information about working with applications, see Manage applications.
On the application entity, you can add data-retention policies. Data-retention policies
determine how long the versions of data are stored on the BlackBerry IoT Platform.
You can specify different data-retention policies based on the category and data object.
The categories that are available are based on the
For information about categories, standards, and data objects, see Working with Data.
The time for the data to be stored can be:
- last value only
- a specified number of days
- all data (since the creation of the data - forever)
If a data-retention policy isn't added to an application, these are the defaults based on the category:
- state: last value only
- alarm: last value only
- component: forever
- log: 30 days
The time that you want to store the data is configurable and dependent on your business rules. For example, you can configure the application to store data in the following manner:
- All data objects in the
logcategory as only last version only
- All data objects in the
statecategory to be last value only but the data object called
restartdatato be forever.
For more information about how to configure data-retention policies, see Configure data-retention.
A device entity (or simply device) represents a single instance of application code running on a physical device. For example, if you create an application called "Hello Cloud", you can run separate instances of that application code on two separate computers. Because you have two instances (or devices), they are represented as two different device entities on the platform and have separate data and UUIDs.
Device entities are the only things that can perform actions on the platform and are used to:
- store data, which are represented as data objects
- upload files and share files with other devices
- manage certificates for device-based authentication
The following illustration shows how file entities and device entities are related:
Devices must be authenticated and authorized to connect to the BlackBerry IoT Platform. Authentication of the individual device is handled using user-based authentication (a BlackBerry IoT Platform account) or device-based authentication (using certificates). For more information about how devices authenticate, see Overview of device-based authentication.
If it's the first time a physical device is connecting using user-based authentication, a device entity is created on the BlackBerry IoT Platform. The device also becomes associated with the user logged in.
After connecting, a device can:
- interact with the data from other devices, provided it has the proper permissions For more information, see Understanding Capabilities and Tags
- update its data in the cloud
- send messages to other devices, see Working with Messaging and Notifications
- upload files, see Sharing files
When you add a device entity, you can generate, download, and add a certificate to your physical device. These certificates digitally identify the device to the BlackBerry IoT Platform and you use it to perform device-based authentication.
Certificates leverage industry standards for certificate management. You can generate a certificate using one of these mechanisms:
- upload the certificate signing request (CSR) to the administration console and then download the generated certificate
- past the CSR to an API call and get the generated certificate from the response of that call
Devices can securely store data on the BlackBerry IoT Platform. The main use case for using the platform is to store data and make it securely available to other devices connected to the platform.
For more information on working with data, see Working with Data.
A file entity (or simply file) represents a single data file that's stored in the cloud and associated with a specific device entity. After files are uploaded to the cloud, they can be downloaded by other physical devices. Access to individual files are secured using capabilities. For more information about capabilities, see Understanding Capabilities and Tags.
Each uploaded file corresponds to a file entity and is identified by a UUID. This means that you can upload multiple files with the same name, but access each file using its UUID. In addition, each file entity includes the following information:
- when the file was created and uploaded in Epoch time (in milliseconds)
- name of the file including its extension
- size of the file
- metadata specified as JSON objects
- a download URL, which specifies where the file can be downloaded from
For more information about working with files, see Working with files.
A Firehose entity (or simply firehoses) allows for the streaming of event data from multiple devices to a common point that accessible for other devices.
The BlackBerry IoT Platform permits you to build an ecosystem of data that streamed to one common entity that can be accessed by other devices. Changes to the data, creation and deletion of files, and lifecycle events (creation, update, or deletion of devices, files, or applications) can be streamed as event data to a common point called a firehose.
Other devices can consume the stream of data from the firehose. Access to the firehose, like other entities is controlled using capabilities.
For more information about firehose entities, see Working with Firehoses.
A tag entity (or simply tags) allows capabilities to be grouped and transposed to other entities. Tags can be created and belong either to an organization or to a user. You can create tags and apply them to different entities. Tags are used to transpose capabilities that the tag itself grants to other entities and capabilities are granted to it.
Tag entities are useful to simplify the management of capabilities. For more information about working with tags, see Using tags to simplify permission management.