In this document, we will go over how to start using Meshmerize and Hive for your devices. If you would like to know more about Hive before proceeding, head out to the Hive User Guide. We will assume in this guide that your devices already have an OS compatible with Meshmerize installed. If you need more information about compatible devices or how to install the right OS for them, have a look at the Device Overview.
You can start using Meshmerize in 5 easy steps
- STEP 1 : Creating an account.
- STEP 2 : Ordering licenses
- STEP 3 : Activating the Licenses on your devices.
- STEP 4 : Creating a Hive Deployment.
- STEP 5 : Activating Hive on your devices.
¶ 1. Creating an account
If your company is not already registered, or if you would like to create a Hive deployment for private usage, you can start by setting an account at the Meshmerize Portal. If you would like to create an account for an already registered company, ask your registered colleague to follow the steps given in the invite a colleague to the Meshmerize Portal section. You will then receive an email containing the instructions to create your account; follow them and head directly to the next section.
In the "Sign up" page, you should see the following form:
Once you have filled the form, and email containing a link to finalize your registration will be sent to the address you gave. Follow this link and you will be able to sign-in to the Meshmerize Portal.
¶ Invite a colleague to the Meshmerize Portal
If you have the required rights, you can send invitations to join your company in the Meshmerize portal. As a rule of thumb, the first member of your company to join the portal will always have these rights.
To do so, click on the "Users" section in the left panel, then click on the "Invite user" in the top right.
You will be prompted for the new member's email address and you can then simply click "Send invitation".
¶ 2. Ordering licenses
Once you are logged in to the Portal, you will land on the Dashboard, as seen below.
In order to use Hive, you will need Enterprise licenses: you can see how many are available for your company in the Licenses block of your dashboard. Active licenses are license for which a device has already been attributed, while Available licenses are those which are already purchased but without devices attached to them. Eventually, each device that you will want to use with Hive will need an active license; how to link an available license to a device will be explained in the next section. In the meantime, you can purchase the enterprise licenses you require by clicking on the "Purchase button", or, if you would like to know more about the different types of license that Meshmerize offer, by following the "Prices" link, on the link side of the page.
Note that a licensed device can only be part of a single Hive deployment at a time. However, if you or your company have several deployments, you can change a device's deployment without purchasing a new license. To change a device's deployment, you can re-do the steps described in the Section 5.
¶ 3. Activating the Licenses on your devices
Once you have enough licenses, there are several options available to you :
¶ If your devices have access to the Internet
If your devices have access to the Internet, they can register themselves to the portal. You can do so via the device's web UI or via the command line.
¶ Tabset
¶ From the Web UI
- If your device uses MeshmerizeOS see: https://docs.meshmerize.net/en/public/meshmerize-quick-start-guide#activate-meshmerize-license
- If your device uses WaveOS see: https://docs.meshmerize.net/en/public/acksys/waveos-guide#h-3-meshmerize-license-registration
¶ From the command line
Each license is associated to a MAC address, a unique identifier of one your device's components. To see the list of available MAC addresses to use for the license, run the command meshmerize register -L. The output will be something like:
wlan0 00:00:00:00:00:00
wlan1 00:00:00:00:00:01
eth0 00:00:00:00:00:02
eth1 00:00:00:00:00:03
Choose one of the device of the left column (which device you choose matters little; eth0 is a convenient choice since most devices have an eth0 device).
Then run the command
meshmerize register -u <USER> -p <PASSWORD> -l enterprise <DEVICE>
where <USER> is the email address you used for your Meshmerize Portal account, <PASSWORD> is the password for this account, and <DEVICE> is the device you have chosen.
¶ If your devices do not have access to the Internet
If your devices do not have access to the Internet, you will need to register them from the portal: go to the "Devices" section in the left panel and click the "License new device" button.
For each device that you want to license, to need to fill its MAC address. If you don't know its MAC address and have access to the device's command line, you can run the command meshmerize register -L.The output will be something like:
wlan0 00:00:00:00:00:00
wlan1 00:00:00:00:00:01
eth0 00:00:00:00:00:02
eth1 00:00:00:00:00:03
Choose one of the address of the right column (which address you choose matters little; the one of eth0 is a convenient choice since most devices have an eth0 device). Note that if you have a list of MAC addresses for the devices that you want to license on hand, you can add several addresses at a time by clicking "Insert multiple MACs". It will open the following field, in which you can enter one MAC address per line.
Once you have entered the MAC addresses, select the "Enterprise license" in the second section, and finally click the "Issue licenses" button at the bottom of the page. You will then be redirected to the device page.
From there, select the devices you have licensed by clicking the box to their left then click the "Download n selected licenses". You will then receive a file named meshmerize.license that you need to copy in the /etc/ directory of your devices. Note that it also possible to use the web UI of the devices to install this file.
- If your device uses MeshmerizeOS see: https://docs.meshmerize.net/en/public/meshmerize-quick-start-guide#activate-meshmerize-license
- If your device uses WaveOS see: https://docs.meshmerize.net/en/public/acksys/waveos-guide#how-to-activate-a-meshmerize-license
¶ 4. Creating a Hive deployment
To create a deployment, you simply need to click on the "Deployments" section of the left panel, then click the "Create Deployment" button. You will be redirected to this form, that you need to fill:
The subdomain may only contain alphanumeric characters and hyphens (i.e letters from A to Z, digits or -; if you enter uppercase letters, they will be converted to lowercase). The purpose of this subdomain is to personalize the URL of the Hive deployment you are creating: if you choose mydomain, the URL of your Hive will be https://mydomain.hive.meshmerize.net. The latest Hive version will be automatically selected in the "Version" field and you do not need to change it.
Once this is done, you will land on a page showing you the details of your deployment.
Note the State section: it will show "Starting" for a small time, while your Hive deployment gets created. Wait a couple of minutes then reload the page.
It should show "Active" instead of "Starting"; you may now follow the URL to visit your Hive deployment.
¶ 5. Activating Hive on your devices
To use the Hive with your device, a separate program, that we call the "Hive worker" needs to be started on your device. Similar to the licensing, this can be done either via the Web UI or via the command line.
¶ Tabset
¶ From the Web UI
- If your device uses MeshmerizeOS see: https://docs.meshmerize.net/en/public/meshmerize-quick-start-guide#optional-connect-the-device-to-hive
- If your device uses WaveOS see: https://docs.meshmerize.net/en/public/acksys/waveos-guide#hive-worker
- If your device is Doodle Labs see : https://docs.meshmerize.net/en/public/doodle-labs/doodle-labs-setup-guide#h-5-optional-hive-worker-setup
¶ From the command line
You need to run the following command from your device:
uci set meshmerize.hive.enabled=1
uci set meshmerize.hive.mqtt_host="<HTTPSURL>"
uci set meshmerize.hive.hive_host="<MQTTURL>"
/etc/init.d/hive-worker reload
where <HTTPSURL> is the URL seen in the previous section, for instance https://mydomain.hive.meshmerize.net. <MQTTURL> is without the prefix or suffix, for instance mydomain.hive.meshmerize.net
¶ Further steps
At this point, you are ready to use your Hive deployment. See the Hive User Guide for an overview of the possibilities offered by Hive.