I know a lot of you have been waiting for this, so I'm not going to bury the lede: The header file describing the Bluetooth protocol the Myo armband uses to communicate with your computer is here.

Read on for more details.

Bluetooth What-ocol?

If you are asking yourself why this would be useful, it's probably not for you. In the hands of an adventurous developer it would allow them to build Myo support for other platforms, like Arduino, BlackBerry, or really anything with a Bluetooth Low Energy (BLE) chip that 1) you can execute your own code on, and 2) can act as a GATT client (a lot can only be the server). So for example, someone could now build an Arduino project that talks DIRECTLY to an attached Bluetooth LE shield, rather than bridging it through a computer. That's pretty cool, and we look forward to seeing what kind of crazy stuff you hook your Myo armbands it up to.

How do you go about doing this? Well, the header describes all the things you can do and what the data will look like, but let me walk you through the expected flow.

Bluetooth Low Energy Basics

If you are already a pro at Bluetooth Low Energy, you can skip this. If not, you will probably want to read up on the protocol (here's a good start) a bit before diving in. I'm going to give you a basic outline of what you'll be doing to talk to any BLE device (and the Myo armband specifically). Chances are whatever platform you are targeting already has a library and some good docs to help you though.

  1. Discover: Start scanning for GAP (Generic Access Profile) peripherals, which is what the Myo armband is. If there is anything available nearby, you should hear about it within a few seconds. The Myo will send advertising packets containing a single 128bit UUID for the Control Service (D5060001-A904-DEB9-4748-2C7F4A124842).

  2. Connect: Assuming you found some Myo armbands, connect to one. Typically you would provide a UI and let the user select the one they want, but on devices where this is impossible you may want to go with a "tap" behaviour that connects based on signal strength, and then use the armband’s MAC address for subsequent connections.

  3. Interact: Now the Myo armband can be treated as a GATT (Generic Attribute profile) server, and your device the client. The armband exposes a set of characteristics (grouped into services) that provide access to data and control of capabilities. Now you can use standard GATT procedures to read and write characteristic values and/or subscribe for notifications or indications (for characteristics that support that functionality).

At this point you are going to start doing Myo-specific stuff. Let's talk about what that will look like.

Don't need this to talk to Arduino!

Myo Bluetooth Flow

We've provided this helpful header file to explain exactly what the Myo armband can give you, and what you can tell it to do in return. You will probably refer to it often when building your implementation, so bookmark it now. You’ll note it has the GATT Characteristic IDs for everything specified. You can use those values for now, but discovery is preferred.

This is what kind of communication you should be expecting once you've connected to a Myo armband.

  1. Read the Myo FirmwareVersionCharacteristic and make sure it's something you're prepared for. Obviously capabilities and what attributes are available could be very different from one firmware version to another. We use semantic versioning (ie, major.minor.build). Basically, if the major version matches, and the minor version is at least what you built for, you should be good. A different major number will indicate a breaking change, and a lower minor may indicated missing features. You would only care about the build number if you need a specific bugfix that didn’t warrant a bump in the minor version.

  2. Subscribe to receive notifications from the characteristics that you are interested in. You probably want IMUDataCharacteristic for motion data and ClassifierEventCharacteristic for pose data at least. You may also want EMG data (broken into 4 different EmgDataXCharacteristic characteristics) but that is expensive battery- and bandwidth-wise, so only use it if you actually need it.

  3. Write control commands to put the Myo into a state you want. By default, the Myo armband isn't going to send IMU/Pose/EMG data just because you're subscribed. It's expensive, so you have to send a certain CommandCharacteristic to turn it on and off. This is how Myo Connect notifies the Myo armband that there is an application listening, for example. See myohw_command_t in the header file.

Myo Commands

You will definitely want to understand myohw_command_set_mode to put the IMU, EMG and Classifier into the states you want. Let's talk about the core commands you need, and a few others you may be interested in.

Core Commands

  • IMU: you probably want myohw_imu_mode_send_data, though you can play around with some experimental tap events with myohw_imu_mode_send_all if you want.

  • EMG: If you want EMG data, you definitely want myohw_emg_mode_send_emg, unless for some reason you want to pick up random interference from nearby power lines or your laptop charger with myohw_emg_mode_send_emg_raw. Setting the EMG mode to raw will also disable the classifier (preventing you from getting pose data) since it's not designed to handle it at all. If you don't want EMG, use myohw_emg_mode_none.

    There is more information on the specifics of the EMG data in this MyoCraft post.

  • Classifier: If you want pose data use myohw_classifier_mode_enabled. If you don't, send myohw_classifier_mode_disabled. This will be useful if you just want to capture IMU and EMG data, but don't want interruptions from, say, the sync gesture being detected. Note that you won't get poses while the Myo armband is either not synced or locked. That behaviour is all controlled on the Myo armband itself. Disabling the classifier will also disable syncing, and the lock mode can be set (time, hold, or none) through the protocol.

Other commands

There are a few other interesting things you can do using the Bluetooth spec.

  • Sleep mode: A big one is the sleep state. If you turn off the classifier, the Myo is going to fall asleep pretty quickly while not synced on someone's arm. To fix that, set sleep mode to myohw_sleep_mode_never_sleep. Note that this is going to be pretty rough on the battery, make sure you turn it back to myohw_sleep_mode_normal when you are done. It should also reset to normal on it's own when you are no longer connected to the Myo armband (as will most settings, actually).

  • Vibrate: Our SDK has a few distinct vibration patterns programmed in for you. For consistency we recommend you use something like that for vibration, but with the protocol you have full control of the power and duration of a vibration. There are probably neat things you can do with this, but keep in mind the average user is not going to be able to recognize and differentiate between many different vibrations happening with no other context. If you don’t believe me, try wearing headphones while trying to distinguish vibration patterns. If you just want to notify a user that they've done an action, use myohw_command_user_action, same as in the SDK.

  • Deep sleep: This will probably be built into a future version of Myo Connect, but it's available through the protocol right now. If you send this command, the Myo armband will go into a deep sleep with everything basically off. It can stay in this state for months (indeed, this is the state the Myo armband ships in), but the only way to wake it back up is by plugging it in via USB. Don't send this command lightly, a user may not know what happened or have the knowledge/ability to recover.

That should be enough to get you going! If you do something cool with the protocol, let us know! Building support for another platform will give you a pretty good shot at being featured in a #MyoCraft post, FYI. And if you get into trouble, or have a sweet proof of concept you’ve got going, come join us in the forums!

Good luck, and happy coding!

Newsletter

Enter your email address and get all latest content delivered to your inbox every now and then.