MUGIC User S Guide 2020
MUGIC User S Guide 2020
DO NOT:
● Attempt to open the case
● Apply any liquid
● Store in hot (above 88F/31C), or humid
conditions
NOTE: Avoid attaching MUGIC™ directly onto the skin for a long
period of time.
USB connector: We recommend to charge MUGIC™ before use (this will take approximately
1 hour). MUGIC™ will immediately begin charging when plugged into a USB power
source supplying 5V with at least 500mA. The device requires at least 5 minutes of
charging before being able to be powered on, if the power is critically low.
Power Switch: Move up to turn ON (away from the USB connector), move down to turn OFF.
Reset Button: When pressed, MUGIC™ will reset to factory defaults.
Mode Button: When pressed, MUGIC™ will switch between WIFI mode (default) and USB
mode. If you see the LED 3 in (Blue) blinks every 1 second, WIFI is active.
LED 1: Red light indicates that the device is charging when connected to USB.
LED 2: Green/Orange/Red indicates the status of the battery
(Green:80+% power remaining, Orange: more than 40%, and Red: less than 40%)
(Blinking red: less than 10% power remaining)
LED 3: Blue light blinking every 1 second means MUGIC™ is transmitting data over WIFI.
While establishing the WIFI network, the blue light will blink as twice as fast.
Troubleshooting: If the WIFI network name doesn’t show up in your computer WIFI, turn
your WIFI off, wait for 15+ seconds and turn back on. It should usually come up immediately,
but it might take a few tries and eventually, it should show up.
WIFI mode and USB mode: MUGIC™ also works in USB mode, connecting to the computer
via a USB cable. In case you need to connect to the internet via WIFI, MUGIC™ can also
keep working via USB mode.
- WIFI mode: MUGIC™ is set to WIFI mode as default. You can also charge MUGIC™
connected to an electric outlet via USB cable, so you won’t run out of power while in
WIFI mode.
- USB mode: MUGIC™ also works in USB mode, connecting to the computer via a
USB cable. In case you need to connect to the internet via WIFI, MUGIC™ can also
keep working via USB mode.
Before use, it is helpful to shake MUGIC™ for a few seconds; this is for sensor’s calibration
purposes. Shake them mimicking the movements of cocktail shakers, with quite fast
motions. Try to also shake in different directions, twisting your wrist. Just a few seconds is
enough.
Note: Please be careful not to throw or drop MUGIC™! The resin casing is fragile and can
easily crack if you drop onto a hard surface.
Download the MUGIC™ App: For configuring your MUGIC™ device, it is recommended to
download the MUGIC™ app (https://mugicmotion.com/mugic-firmware). The app offers
menus for all of the operations in the next section.
Troubleshooting: If the USB mode doesn’t seem to work in Max or LIVE, make sure you quit
MUGIC.app and try again. A USB port can’t connect to multiple apps.
Troubleshooting:
If you joined the MugicConnectXXXXXX network, but are not receiving any data:
Check your local IP (in your computer’s settings or system preferences, network
configuration). It should be 192.168.4.2 (the device should have the IP address
192.168.4.1). If this is not the case, you may not be the only computer or device to
join the access point. Try turning off the device and back on, then join again.
Alternatively, in a browser, while MUGIC™ is on WIFI, visit URL
http://192.168.4.1/set?udp_ip=192.168.4.X where 192.168.4.X is your local IP
address. (It’s possible that the WiFi network be 10.0.0.1 or something else. In that
case, use the router address of your WIFI network instead of 192.168.4.1.)
Data API
Once your computer receives the data over either WIFI using port 4000, or over USB, you will
receive datagrams with the given format:
● Over WIFI: UDP network packet addressed to computer IP over port 4000.
Contents: OSC Message “/mugicdata AX AY AZ EX EY EZ GX GY GZ MX MY MZ
QW QX QY QZ Battery SysStatus GyroStatus AccelStatus MagStatus Secs
SeqNum” (“A”=accelerometer, so AX AY AZ means the acceleration of X, Y and Z
angles. See page 6 “MUGIC™ Datagram and description”)
● Over USB: discard any line on the serial port not beginning with “mugicdata” (or pipe it
into a log, since they consist of logging/debugging information indicating state transitions
and other operations of the MUGIC™ device). The lines containing data have the
format: “mugicdata AX AY AZ EX EY EZ GX GY GZ MX MY MZ QW QX QY QZ
Battery SysStatus GyroStatus AccelStatus MagStatus Secs SeqNum”
(Note: Depending on the flags, some of these data may be 0. They are all on by default.)
The values are provided by the on-board BNO055 integrated sensor, whose full documentation
is provided on the vendor’s website. The most useful values for the average user are
acceleration and quaternion orientations.
Euler Angles 456 Euler angles: computed by the on-board sensor from the
EX EY EZ quaternion, in (fixed) Earth-related frame, in degrees.
These values are read from the device in native resolution of 100Hz (every 10ms), however it is
not possible for the on-board software to read and publish this data at this rate over USB. The
current reading and publishing frequency is set at a default of 40Hz, i.e. loop_delay of 25ms.2,3
1
With a reasonably steady rate, should be spaced every 25ms per consecutive messages, but can vary depending
on various interactions and activity in the device (e.g. network activity). Can be regulated through the loop_delay
parameter (see next section).
2
The most efficient way to publish data we have come about is over OSC messages, via WIFI, and turning off any
non-essential measurements (which would then be published as 0) as indicated by the flags section in the next
section. Using this we can achieve a consistent 15ms loop-delay, and with occasional fluctuations even 10ms (but
some measurements might occasionally be spaced apart by more than 10ms).
3
We are currently researching the possibility of publishing “raw” non-OSC messages, but this would likely be a
non-portable non-standard modification - please contact us if you need this level of accuracy and publishing
frequency.
All commands below modify the RAM state; these changes will be lost if the device is
powered off, or if the configuration is reloaded from EEPROM using the reload command.
They can be saved into the EEPROM by using the commit command. The reset command
will erase the state of the EEPROM and overwrite with the default / factory settings, similar to
what can be obtained from pressing the RESET button.
The state of your device consists of the following main parameters with the following values:
etc.
This page tells you about the configuration of your device. You can visit it any time to
check on your changes. You can modify any of the parameters by visiting e.g.
http://192.168.4.1/set?name=MyMUGIC, for instance, to change the name of your
device from Mugic469106 (in the example) to MyMUGIC.
Note: special characters like ‘ and (space) need to be encoded like
http://192.168.4.1/set?name=Mari%27s%20MUGIC™ to set the name to “Mari’s
MUGIC™”. The same goes for any other parameter (like ap_ssid and wifi_ssid). The
MUGIC™ app does that for you.
You can switch between WIFI mode and USB mode, by visiting the commands
http://192.168.4.1/wifimode or http://192.168.4.1/usbmode.
Please remember that all these modifications affect the values stored in RAM. To save
these values to EEPROM, visit http://192.168.4.1/commit. To discard your changes,
visit http://192.168.4.1/reload. To reset the MUGIC™ device to factory settings, visit
http://192.168.4.1/reset. For further info, visit http://192.168.4.1/help.
Over USB
You will need a program such as Minicom, Putty, or the Arduino IDE, to access the
port (typically COM[0123] on Windows, SLAB_USBtoUART on MacOS). In that
terminal, enter commands such as “print” to see the configuration state, or
“name:MyMUGIC™” to change the name of your device.
Available commands and their arguments include (do not type the surrounding quotes,
and change the ALL CAPS values to the values you desire):
● “print” to see the state of your device (it is recommended to turn “usb:0” to
avoid the print statements to be drowned in MUGIC™Data messages)
● “name:NAME OF YOUR DEVICE” to name your device
● “wifimode” or “usbmode” to switch between WIFI mode or USB mode.
● “ap_ssid:NAME OF YOUR NETWORK”
● “ap_pwd:PASSWORD” (must be at least 8 chars long, or else the device will
not be able to create the access point in AP mode)
● “ap_port:PORT” (default is 4000 but if using several MUGIC™ devices, you
may want to give each a different port number)
● “wifi_ssid:NAME OF YOUR WIFI CLIENT NETWORK”
● “wifi_pwd:WIFI NETWORK PASSWORD” (must be at least 8 chars long, or
else the device will not be able to join an existing network in Client mode)
● “wifi_ip:IP.ADD.RE.SS” (default is 192.168.4.1, but if joining in client mode, you
will need to configure to your computer’s IP address on the common network)
● “wifi_port:PORT” (default is 4000 but if using several MUGIC™ devices, you
may want to give each a different port number)
IMPORTANT: First, make sure to quit Max, Ableton or other applications connecting
MUGIC™ to computer via USB
Troubleshooting: If you are using a public network, make sure it is enabled to forward the
MUGIC™ data on a given port. We generally do not recommend using a public network, since
such data forwarding via UDP may be forbidden, and the ports are blocked; contact your local
network administrator. After you connect your computer to it, you need to record the IP
address of your computer on that network. (You can obtain that information from the network
settings; if you need help, this page has it.)
If your computer will create the client network, then you have freedom to choose the network
name and password, and your local IP address. Let’s set your network to ‘JigglyCat’ (it needs to
be at least 8 characters), your password ‘JigglyDog’ as an example. We will also assume that
your computer will have the local IP address 192.168.4.1.
Technical notes: Typically, MUGIC™ devices that join the network will have IP addresses
192.168.4.{2,3,4…} but it doesn’t matter, since they send the data to the computer all that
they need to known is the local IP address of the computer.
TroubleShooting: If you don’t see the IP address, go to System Preference - Network, Click
Advance at the bottom, and Press “Renew DHCP lease”, then press Apply.
● Open MUGIC.app
● Connect MUGIC™ to computer via USB, then turn the power ON.
● For each MUGIC™ device, name and create your network. Set:
- wifi_ssid to “JigglyCat”
- wifi_pwd to “JigglyDog”
- wifi_ip:192.168.4.1
- different port numbers for each MUGIC™
- wifi:c
- commit
● Now, turn the MUGIC™ power OFF, then back ON, and set MUGIC™ to Client Mode.
3.2 MacOSMac users: you need to have an internet connection to share. If you are not
connected to a network, you can create a ‘bogus’ Ethernet connection (loopback, see below) so
Mac ‘thinks’ there is a connection to share with multiple MUGIC™.
Troubleshooting: (if you don’t have Ethernet, then go to “3.3 Loopback method” on
page 14, then come back here to go to step 3 below)
3. Go to the Systems Preferences and open the “Sharing” panel. Choose “Share your
connection from: <USB/Ethernet>” and “To computers using: [x] WIFI” as in the picture
below. If it asks you to ask the ‘WIFI on” press ‘cancel’ for now.
Also click on the WIFI Options, and configure the network using the parameters of your
MUGIC™ device, as in below. (If using the factory defaults, MugicNetworkXXXXXX and
mugicXXXXXX; if you already have set your own wifi_ssid and wifi_pwd, then use those
values.)
And click on the “Advanced” button, select the TCP/IP tab, and set the following parameters.
Click OK, Apply, and exit the Systems Preference. Your mac should now have created its own
network called MUGIC™NetworkXXXXXX with password as mugicXXXXXX, and have the IP
address of 192.168.4.1 on that network.
3.3 Creating your local network for MacOS users with Loopback method:
If the above method does not work, or you do not have any connection to the internet that you
can share, then you must first establish a loopback. (This makes your computer act like it’s own
little internet server.) Sadly, it’s not easy. The following method was lifted (with thanks and
acknowledgments) from https://www.laszlopusztai.net/tag/wireless-tethering/page/3/. First,
open a Terminal (using Spotlight, -Space) and enter the following instructions starting with
“sudo networksetup…” (you need to have administrator privileges). Enter your password if
prompted.
Technical Details: Macs unfortunately don’t have the same sort of virtual network interface
feature. To share a WIFI connection over WIFI, you’ll need a separate physical WIFI interface,
for example a hotspot device like the RAVPower mentioned above. You can create your own
network, but then you will not be able to connect to the internet while working with MUGIC™.
(This may actually be desirable to avoid possible interruptions due to an external connection.)
In order to quit working with MUGIC™ and return to your Internet access, you will need to
undo these changes. For these reasons, it is quite advised to create a different Location in
the Network system preferences, called MUGICXXXXXX, and to switch between Automatic
(your internet connection) and MUGICXXXXXX (your local network for MUGIC™).
Appendix
MUGIC™ Care
The casing is made of resin, 3-D printed in two parts: the top cover and the bottom. If you drop
MUGIC™ and the casing comes apart for some reason, you can glue it back carefully using a
‘super glue’, or any cyanoacrylate adhesives. Gorilla Glue, Loctite, Krazy Glue, others all
make cyanoacrylate adhesives. For example:
Gorilla 7805601 Super Glue, 20 g, 1-Pack
https://www.amazon.com/dp/B00KPYB05A/ref=cm_sw_r_cp_api_i_hOS5EbYZRY2WC
Data Specs
Q. How frequently is it sampled from the device / how much data does the device send?
A. The data is sampled by default every 25ms (40Hz) and sends a single UDP packet of
less than 512 bytes, as a result the network traffic is minimal. The frequency can be
adjusted through the loop_delay parameter, but the device maximum frequency is every
10ms (100Hz) and it is hard to configure the sensor to achieve this throughput.
Q. How physically accurate is MUGIC™?
A. The sensor integrated in MUGIC™ is a Bosch BNO055, one of the best fused IMU on
the market. For technical documentation incl. range and accuracy, please see their
documentation (https://cdn-shop.adafruit.com/datasheets/BST_BNO055_DS000_12.pdf)
Q. Can I track absolute position with MUGIC™?
A. This is a hard problem with any IMU sensor, since they only provide orientation and
acceleration, not speed or position. For instance, it is physically impossible to distinguish
a device traveling at constant speed from an immobile device since in both cases
acceleration is zero. Using additional constraints (such as when the device is mounted
on a doorframe or other physically -constrained element, or if the device undergoes a
cyclical motion such as a rotation about a fixed axis) it is possible to achieve excellent
positioning. For a free-form sensor like MUGIC™, it remains an active research project
to estimate accurate speed and position, although in theory using physical constraints
from an instrument such as a violin (if mounted on the box hand) should help.
https://cdn-shop.adafruit.com/datasheets/BST_BNO055_DS000_12.pdf?fbclid=IwAR39i
BXEzhbg2LK9Cv4X-RsQeHW8es390-tidt0F-jdZSAhF7Ba_Mfz5J4g