In this tutorial we will illustrate how you can connect to the Mionix Device Hub running on your PC through a WebSocket API in order to interact with your Naos QG. It is assumed that you know some web development and that you are familiar with JQuery and Bootstrap 3, since we will be using these libraries for illustrating the API. They are ofcourse not required and you may choose any other framework.
First of all you need to create a new WebSocket in your javascript by connecting to the Hub at ws://localhost:7681 . The API is specified by the protocol name mionix-beta. Here is an example on how to connect to the Hub and detect a successful connection:
var mionixSocket = new WebSocket("ws://localhost:7681", "mionix-beta");
mionixSocket.onopen = function () {
// Assuming there is a html element with id="connectLabel" and class="label label-default".
$("#connectLabel").addClass("label-success");
$("#connectLabel").text("Connected");
};
mionixSocket.onerror = function () {
$("#connectLabel").addClass("label-danger");
$("#connectLabel").text("Not connected");
};
Below is a demonstration of the above code. If the server is running then you should see Connected, otherwise you should see a Not Connected. Note, that you might need to refresh the page if you recently started the Hub.
Whenever a Naos QG is plugged in or plugged out, a message (a JSON object) with attribute "type": "devices", is sent to all connected WebSocket clients. Whenever the dpi or the profile of the mouse is changed a message with attribute "type": "deviceChanged" is sent. Here is an example on how to receive these messages on the client side:
mionixSocket.onmessage = function (message) {
var data = JSON.parse(message.data);
if (data.type == "devices") {
// Handle devices message here:
}
else if (data.type == "deviceChanged") {
// Handle deviceChanged message here:
}
};
When plugging out your Naos QG, the message will only contain the "type" property. But when plugging it back in, the message will also have an array "devices": [ ... ] containing objects with information about the connected devices. Each object in the array will have the following attributes.
type will always be "devices".
deviceInfo containing the device name, firmware version and whether it is "normal" or "boot" mode. capabilities containing various device specific contants. profiles listing all the profiles and their current values. selectedProfileIndex showing the index of the selected profile in the profiles array. selectedProfileIndex showing the index of the selected dpi in the selected profile. Whenever the mouse dpi or profile changes (by clicking the dpi or profile mouse button) a message containing information about that change is sent to all clients.
type will always be "deviceChanged".
deviceIndex showing the index of the device in the "devices" array. selectedProfileIndex showing the new index of the selected profile in the profiles array. selectedProfileIndex showing the new index of the selected dpi in the selected profile. Below is a demonstration of the above code. Plug/unplug your Naos QG or change its dpi/profile to see what message is sent:
While your Naos QG is plugged in (and not in boot mode), a message (a JSON object) with attribute "type": "mouseMetrics" and another message with attribute "type": "mouseMetrics" are continiously sent to all connected WebSocket clients. Here is an example on how to receive these messages on the client side:
mionixSocket.onmessage = function (message) {
var data = JSON.parse(message.data);
if (data.type == "bioMetrics") {
// Handle bio metrics message here:
}
else if (data.type == "bioRaw") {
// Handle bio metrics message here:
}
else if (data.type == "mouseMetrics") {
// Handle mouse metrics message here:
}
};
The bioMetrics message will have the following attributes:
heartRateState the current state of the heart rate sensor. heartRate the current heart beats per minute. heartRateQuality the quality of the current measurement in percentage. heartRateAvg the average heart beats per minute since a few seconds. heartRateMax the maximum heart beats per minute since a few seconds. The heartRateState attribute will have the string value "idle" while the sensor is not active. When the user's hand is on the sensor and the calculation is in progress the value will be "preparing". Finally the value should switch to "active", which is when you may read the attribute heartRate to get the calculated bpm along with heartRateQuality indicating the quality of the calculation between 0 and 100 percent.
If the user takes the hand off for a short while, the state will go thorugh the phases "recovery_idle" and "recovery_preparing" while the sensor is trying to pick up the heart rate again. While in recovery mode, the previous heart rate is still shown.
If the user has turned off the sensor the value will be "off".
The bioRaw, available from Hub version 0.13, contains the raw value from the sensor. This message is only sent when the sensor is on. Note that the sensor is switched off a few seconds after the sensor detects that there's no touch.
dt times in ms since laste sample.heartRate reflective value from the sensor.touch indicates hand on or off.The mouseMetrics message will have the following attributes:
totalTime the time the mouse has been active since factory reset. totalDistance the distance moved since factory reset. totalScrolls the number of steps scrolled since factory reset. totalClicks the number of clicks since factory reset. streakTime the time the mouse has been active during the last continuous gesture. streakDistance the distance moved (in millimeters) during the last continuous gesture. streakScrolls the number of steps scrolled during the last continuous gesture. streakClicks the number of clicks during the last continuous gesture. speed The current movement speed of the mouse. speedAvg The average movement speed since a few seconds. speedMax The maximum movement speed since a few seconds. clickRate The current click rate of the mouse. clickRateAvg The average movement click rate since a few seconds. clickRateMax The maximum movement click rate since a few seconds. scrollRate The current scroll rate of the mouse. scrollRateAvg The average movement scroll rate since a few seconds. scrollRateMax The maximum movement scroll rate since a few seconds. The attributes starting with "total*" are saved on the flash memory of the Naos QG and contain data since the device was last reset. This data is not lost when upgrading the firmware. However in order to protect the device memory from wearing out, the total metrics are never saved more than every 10 minutes. This means that the total values might decrease slightly to the last saved state after replugging your Naos QG.
All times are given in milliseconds, distances in millimeters and speed in meters per second. Click rates and scroll rates are given in counts per second.
Below is a demonstration of the above code. Make sure your Naos QG is plugged in to see what information is sent in the bioMetrics and mouseMetrics messages: