Quick Start Guide

Magistrala provides core Services for handling the creation, deletion, updating, and retrieval of user accounts, devices and channels. Users in Magistrala must have unique credentials, including a username, secret, and email address upon creation.

This guide will take you through the core services for a quick setup of Magistrala and a walkthrough of its services and components.

Sign Up

To get started, create an account by providing the following details in the Sign Up page:

• First and last name
• An email address
• A username

NB: Please review and accept our Terms of Service and Privacy Policy to proceed with registration.

Sign Up with Google

Alternatively, you can create a new Magistrala account using Google Sign-Up.
On the Sign Up page, check the boxes for:

• I agree to the Terms of Service
• I agree to the Privacy Policy

Then click Sign up with Google.

Select your Google account to complete registration. You’ll be redirected to the Workspaces Homepage, where you can create or join existing workspaces.

Verify Your Email

After signing up, you’ll be redirected to your Profile Page, where you’ll need to verify your email before proceeding.

A confirmation email will be sent to the address you registered with.
Open the email titled “Welcome to Magistrala!” and click on the Verify Email Address button.

If the button doesn’t work, you can also copy the verification link provided in the email and paste it directly into your browser.

Important:
The verification link is valid for 24 hours for security reasons.
If it expires or you didn’t receive the email, click Resend Email Verification on your profile page.

Once verified, your profile status will update to Verified, and you’ll gain full access to the platform, including the ability to log in to workspaces.

After Verification

After your email has been verified:

• You’ll be redirected to the Workspaces Homepage.
• From there, you can create a new workspace or access any existing ones you belong to.

Tip: If you’ve already verified your email and are still on the verification page, click Go to Workspaces Page to continue.

Log In

In case you already have an account, you can log in with your email/username and password.

Magistrala also supports authentication using Google Sign-In for faster and more secure access. On the Sign In page, click Sign in with Google.

You’ll be redirected to a secure Google authentication page like the one below.

Choose your preferred Google account to continue. Once authenticated, you’ll be redirected back to Magistrala and automatically logged in.

Note:
If this is your first time signing in with Google, Magistrala will automatically create a new user profile associated with your Google email.

Log into a Workspace

Upon logging in, users are redirected to the Workspace Selection Page.

A Workspace lets you manage Devices, Channels, Groups, Dashboards, Members, Rules and Bootstrap services.

Click the + Create button in the top-right corner to start. In addition to the workspace name, you’ll need to set a route, a unique, user-friendly alias for the workspace’s ID. This route makes it easier to reference or subscribe to the workspace without using its full UUID.

The route is defined only at creation and cannot be changed later, so choose something short, clear, and descriptive.

Once you create a workspace, you are given admin role over the workspace by default. You are able to perform all actions available over the workspace and all the entities provisioned inside the workspace. You can also assign or invite members to the workspace with various levels of permissions. Click on the respective card to log into a workspace of your choice.

We will delve deeper into Workspaces in another section. For now you need to be able to log into a Workspace to move on to Groups.

Create a Group

Once logged in, you will be directed to the Homepage where you can view all the available entities in the workspace.

On the sidebar navigation, click on Groups under the Device Management section to be redirected to the groups page.

To create a group, click on the + Create button present on the top-left corner of the page. This will open a popover with all the required fields for a new group.

Create a Device

A Device represents a device connected to Magistrala, capable of communication with other devices. It can be a physical or virtual device that sends and receives messages, often through embedded systems.

When you create a device within a specific group, it is automatically assigned to that group and can be connected to any channel in the workspace.

To create a new device, go to the Devices page of the desired group and click the + Create button.
A dialog will appear asking for details such as:

• Name (required)
• Key (optional) - The device key is used to authorize the device to send messages. If left blank, a key is auto-generated during device creation. Users may also provide their own key, and it can be edited later.
• Tags (optional, for organization and filtering)

Adding tags can help you quickly locate and manage devices in larger setups.

A user can also create bulk devices by clicking on the Upload button. This will lead to a dialog box that takes in a .CSV file with the device's details filled in correctly as seen in these samples.

The file should have the following fields in order:

1. Name (Required)
2. Metadata
3. Tags

View a Device

Once created, a group-device can be viewed and updated in the unique Device's ID page. To open this page, click on the desired device in the Devices table.

From the Device Details page, you can:

• Update the device’s information
• Copy its ID and secret
• Manage its connections
• Manage the Device's Roles as well as Members
• View the Device's audit logs

The Connections tab in the group-device page is where a User can connect a Device to a Channel.

Create a Channel

Channels act as message conduits, enabling communication between devices.

They serve as topics that multiple devices can publish to or subscribe from, allowing seamless device-to-device messaging.
While subtopics are supported for more granular message routing, they are optional for basic interactions.

Each channel has a route, which is a user-friendly alias for the channel’s ID.
The route makes it easier to reference or subscribe to the channel without needing the full UUID.
It is defined only during creation and cannot be changed later, so choose something short, clear, and descriptive.

To create a channel, navigate to the fourth tab under the groups and click on + Create. This will open a dialog box which will take in a unique Channel name. Much like the Devices, clicking on Upload will allow a user to upload a .CSV file with multiple channels.

View a Channel

After the Channel is created, clicking on it while it is on the Channels table leads to the Channel View Page.

Devices can be connected to channels in groups. This is done in the Connections tab. There are two connection types:

• Subscribe
• Publish

Create a Rule

To store any messages in the Magistrala database, you must first create and save a Rule using Rules Engine.

Navigate to the Rules Engine section on the navigation bar and click on + Create. You will be taken directly to the Rule Creation page, where you can start building your rule by adding the required nodes.

Building the Rule

1. Add Input Node

   • Click Add Input and choose Channel Subscriber.
   • Select the channel you want to subscribe to from the list.
   • (Optional) Add a topic for more specific filtering.
   • The input node will now appear on the canvas.

2. Add Logic Node

   • Click Add Logic and choose Lua Script Editor.
   • There is a default logicFunction that can return the SenML payload of incoming messages or you can enter your own rule logic, for example:

function logicFunction()
 return message.payload
end

3. Add Output Node

   • Click Add Output and choose Internal DB to store messages in the Magistrala Postgres database.

4. (Optional) Add Schedule

   • Click Add Schedule to open the scheduler dialog.
   • Set the Start Time, Recurring Interval, and Recurring Period as needed.

Save a Rule

Once you have added all required nodes (Input, Logic, and Output), click Save Rule.
A dialog will appear where you can enter the Rule Name and optional Tags.
Click Create to save the rule.

Your new rule will now appear in the Rules table, ready to process incoming messages.

More information about Rules Creation and Updating can be found in the Rules Engine Section

Send a Message

Once a Channel and Device are connected as well as Rule created, a user is able to send messages. Navigate to the Messages tab of the Group-Channel and click on Send Messages.

This will open a dialog box where all the required fields bear an asterisk. Messages are sent via HTTP protocol in the UI.

Users can also send messages using curl commands for HTTP or via MQTT.
Here are some examples:

Using HTTP:

curl -s -S -i --cacert docker/ssl/certs/ca.crt -X POST -H "Content-Type: application/senml+json" -H "Authorization: Client <device_secret>" https://localhost/http/m/<workspace_id>/c/<channel_id> -d '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]'

Using MQTT:

mosquitto_pub -I <device_name> -u <device_id> -P <device_secret> -t m/<workspace_id>/c/<channel_id> -h localhost -m '[{"bn":"some-base-name:","bt":1.276020076001e+09, "bu":"A","bver":5, "n":"voltage","u":"V","v":120.1}, {"n":"current","t":-5,"v":1.2}, {"n":"current","t":-4,"v":1.3}]'

The messages table will then update to include the message sent with the latest message appearing first. Using the filter options, you can filter through a wide range of messages based on the protocol, publisher or even value.

Some advanced filters allow the user to filter based on the required value type, such as boolean or string values. The time filter allows the user to select a date and define a specific time window using the date-time picker. The user can also find aggregate values of messages provided they add an interval as well as a From and To time. With these values you can get the Maximum, Minimum, Average and Count value of messages within a certain time period.

The user can also download a list of messages based on selected filters and view them in a .csv file by clicking the Download Messages button at the top right of the messages table.

Messages provide a core service for our IoT platform especially when it comes to the Dashboards service.