Myo SDK – 0.9.0
Myo Script API Reference

Myo Connect provides a facility for running Lua scripts to control applications using Myo.

This page describes the API for doing so. For examples with explanation, see the Writing Myo Scripts page.

The Lua Environment

Lua is a simple scripting language that is often used for application scripting. To learn more about Lua, visit its homepage or read its documentation.

Myo Connect provides the standard Lua libraries package, coroutine, table, string, bit32, and math. io, os and debug libraries are not provided. Scripts may not access the filesystem.

Global Variables

Script ID

Every script must set the scriptId variable to a unique identifier. Typically this follows the "reverse domain name" convention:

scriptId = 'com.example.someapplication'

Script Title

Every script should set the scriptTitle variable to a user-friendly name. This will be used to identify the script to the user in the Application Manager Window of Myo Connect.

scriptTitle = 'My Awesome Application'

Script Details URL

Every script should set the scriptDetailsUrl variable to the URL of a page that explains to users how the script behaves. This will be used to provide a details link in the Application Manager Window of Myo Connect. Ideally it should point to your application's page in the Myo Market. You can determine the URL it will have by creating the draft application in the developer portal, taking your App ID (the large hexidecimal number in the URL), and putting it in the following string, at the end:

scriptDetailsUrl = "https://market.myo.com/app/\<Your app ID here\>"

Thus, for the iTunes Connector, it would look like this:

scriptDetailsUrl = "https://market.myo.com/app/5474ccf8e4b081c4011c77ae"

Platform

The platform variable provides scripts with information about the platform Myo Connect is running on. It can be either "Windows" or "MacOS".

Callback Functions

Myo Connect calls into the following functions in all Lua scripts. Scripts should implement all of them.

activeAppName()

Called to query the name of the application the script is controlling. Note that scripts may control multiple applications, but that this function should return the current one. This value is used by Myo Connect to display a notice informing the user that the application may be controlled by Myo the first time it gains focus.

Returns
a string representing the name of the application the script is currently controlling.

onForegroundWindowChange(app, title)

Called when either the name of the foreground application or the title of the foreground window changes. The foreground window is the window currently receiving keyboard and mouse events.

Returns
true if the script wants to become active based on the current foreground window, false otherwise.
Parameters
appOn Mac OS X, this is the bundle identifier of the foreground application. On Windows, this parameter is the executable filename of the foreground application. For example, "Myo Connect.exe".
titleThe title of the foreground window.

onActiveChange(isActive)

Called whenever the script becomes active or inactive.

Parameters
isActiveWhether or not the script is now active.

onUnlock()

Called whenever the connected Myo becomes unlocked, as long as the script is active.

onLock()

Called whenever the connected Myo becomes locked, as long as the script is active.

onPoseEdge(pose, edge)

Called for the start and end of every pose detected by the connected Myo, as long as the script is active. Aside from poses explicitly detected by Myo, there are also "rest" and "unknown" poses. The pose is considered "rest" whenever the user isn't doing any particular pose, and "unknown" when Myo is unable to determine even that (e.g. because the user isn't wearing Myo at all, or Myo is disconnected). Pose events still trigger for rest and unknown, so, for example, when a user starts making a fist, the script will typically receive an onPoseEdge("rest", "off") followed by an onPoseEdge("fist", "on").

Parameters
poseThe name of the pose.
edge"on" when the pose starts, "off" when it ends.

onPeriodic()

Called every 10 milliseconds, as long as the script is active.

API Functions

Myo Connect provides the following functions for use by scripts.

myo.vibrate(vibrationType)

Vibrate the connected Myo.

Parameters
vibrationTypeThe type of vibration. One of "short", "medium", or "long".

myo.getArm()

Returns which arm Myo is being worn on.

Returns
"left", "right" or "unknown".

myo.getXDirection()

Provides the orientation of Myo on the wearer's arm. The value represents the direction in which the positive X axis of Myo's coordinate system faces.

Returns
"towardWrist" if Myo's positive X axis is facing the wearer's wrist, "towardElbow" if Myo's positive X axis is facing the wearer's elbow, "unknown" if unknown.

myo.getTimeMilliseconds()

Get the number of milliseconds since some (unspecified) period in time. This can be used for duration effects. See onPeriodic.

Returns
the number of milliseconds since some unspecified period of time.

myo.debug(output)

Print a string to the Myo Connect debug window.

Parameters
outputThe string to be output.

myo.getOrientationWorld()

Get a unit vector representing the direction Myo is facing in the world reference frame. X and Y axes are parallel to the ground, while the Z axis faces up, perpendicular to the ground.

Returns
Unit vector representing Myo's orientation. (Returns 3 values). Delimit return values as follows: x,y,z = myo.getOrientationWorld().

myo.getRoll()

Get an angular value for Myo's orientation about its X axis, i.e. the wearer's arm. Positive roll indicates clockwise rotation (from the point of view of the wearer).

Returns
Myo "roll" value, in radians.

myo.getPitch()

Get an angular value for Myo's orientation about its Y axis. Positive pitch indicates the wearer moving their arm upwards, away from the ground.

Returns
Myo "pitch" value, in radians.

myo.getYaw()

Get an angular value for Myo's orientation about its Z axis. Positive yaw indicates rotation to the wearer's right.

Returns
Myo "yaw" value, in radians.

myo.getGyro()

Get the angular velocity of Myo about its axes, in radians / second.

Returns
Angular velocity of Myo about its X, Y and Z axes. (Returns 3 values). Delimit return values as follows: x,y,z = myo.getGyro().

myo.getAccel()

Get the acceleration of Myo in its own reference frame in units of g.

Returns
Acceleration of Myo along its X, Y and Z axes in its own reference frame. (Returns 3 values). Delimit return values as follows: x,y,z = myo.getAccel().

myo.getAccelWorld()

Get the acceleration of Myo in the world reference frame in units of g. World reference frame values are such that the X and Y axes are parallel to the ground while the Z axis faces up, perpendicular to the ground.

Returns
Acceleration of Myo in the world reference frame. (Returns 3 values). Delimit return values as follows: x,y,z = myo.getAccel().

myo.keyboard(key, edge, modifiers...)

Send a keyboard event to the foreground window.

Parameters
keyThe key to send. One of:
  • Letters, in lowercase: "a" to "z"
  • Numbers: "0" to "9"
  • Function keys: "f1" to "f20"
  • Arrows: "left_arrow", "right_arrow", "up_arrow", "down_arrow"
  • Navigation: "home", "end", "pageup", "pagedown", "backspace", "delete", "space", "tab", "return"
  • Punctuation: "backtick", "minus", "equal", "leftbracket", "rightbracket", "backslash", "semicolon", "quote", "comma", "period", "forwardslash"
  • Modifier keys: "left_shift", "right_shift", "left_alt", "right_alt", "left_control", "right_control", "left_win", "right_win" (Windows), "left_command", "right_command" (Mac), "function" (Mac)
  • Miscellaneous: "capslock", "escape"
edgeThe action on the key. One of "up", "down", or "press" (which is "down" then immediately "up").
modifiersZero or more modifier keys. Supported modifiers are "shift", "control", "alt", "command" (Mac OS X only), and "win" (Windows only).

All punctuation keys listed above are done so by the lower character printed on the key. For example "comma" for comma/left angle bracket, "forwardslash" for forward slash / question mark, and so on.

All keyboard events are based on a US keyboard layout.

Modifier keys are used for multi-key input with modifier such as shift-A (for capital "A"), control-Z, and so on. This represents pressing the modifier keys before pressing the key itself. Modifier keys used as the key parameter represent pressing that key on its own.

myo.mediaKey(key)

Send a system media key event.

Parameters
keyThe media key to send. One of "mute", "volume_down", "volume_up", "play_pause", "next", or "previous".

myo.mouse(button, edge, modifiers...)

Send a mouse click event at the mouse cursor's current position.

Parameters
buttonThe mouse button to click. One of "left", "right", "center", "button_4" or "button_5". Buttons 4 and 5 are available only on Mac OSX.
edgeThe action of the button. One of "down", "up" or "click."
modifiersZero or more modifier keys. Supported modifiers are "shift", "control", "alt", "command" (Mac OS X only), and "win" (Windows only).

Modifiers are optional, and are released after the mouse event.

myo.mouseScrollBy(value)

Send a mouse scroll wheel event.

Parameters
valueThe number of mouse wheel units. Value is signed - positive is wheel up, negative is wheel down.

myo.centerMousePosition()

Set the mouse position to the center of the primary display.

myo.controlMouse(enabled)

Enable or disable mouse positioning based on movement of armband.

Parameters
enabledBoolean value specifying whether or not to move mouse cursor based on movement of the armband.

State is set to the script's last set value when it becomes active. Default state is false.

Mouse movement is automatically disabled when script becomes inactive.

myo.mouseControlEnabled()

Get the state of mouse positioning.

Returns
Whether or not mouse positioning is enabled for the script.

myo.presentationPointer(enabled, tailEnabled)

Enable or disable presentation pointer based on movement of armband.

The presentation pointer is displayed on top of everything on the screen, on all displays, in the same relative position on all displays. Control of motion is identical to that of mouse control.

Parameters
enabledBoolean value specifying whether to display the presentation pointer.
tailEnabledBoolean value specifying whether to the presentation pointer should include a tail.

myo.presentationPointerEnabled()

Get the state of the presentation pointer.

Returns
Whether or not the presentation pointer is enabled.

myo.presentationPointerTailEnabled()

Get the state of the presentation pointer's tail.

Returns
Whether or not the presentation pointer's tail is enabled.

myo.centerPresentationPointer()

Position the presentation pointer to the centre of each display.

myo.presentationPointerZoom(zoomIn)

Trigger an animated zoom effect on the screen into or out of the current location of the presentation pointer. If a zoom is already in progress, calling this will retarget the effect to the current location of the presentation pointer. Zoom effect is seen on all displays, and is animated.

Parameters
zoomInWhether to zoom in to point or back to unzoomed state.

myo.presentationPointerZoomActive()

Get the state of the presentation pointer zoom.

Returns
Whether or not the presentation zoom is active.

myo.midi(channel, type, data1, data2)

This functionality is currently only available on Mac OS X.

Send a MIDI event through Myo Connect's MIDI interface.

Parameters
channelThe target channel number / device ID, from 0 to 15 inclusive.
typeThe type of message to send. One of "noteOn", "noteOff", "polyAftertouch", "controlChange", "programChange", "aftertouch" or "pitchBend". This value determines the meaning of parameters data1 and data2.
data1First data value for the message, depending on the message type. For more detail, see a MIDI reference.
  • "noteOn" : note (0 to 127)
  • "noteOff" : note (0 to 127)
  • "polyAftertouch" : note (0 to 127)
  • "controlChange" : controller number (0 to 119)
  • "programChange" : program number (0 to 127)
  • "aftertouch" : pressure (0 to 127)
  • "pitchBend" : amount (0 to 16383)
data2Second data value for the message, depending on the message type. As with parameter data1, values depend on message type. Unused parameters should be omitted completely.
  • "noteOn" : velocity (0 to 127)
  • "noteOff" : velocity (0 to 127)
  • "polyAftertouch" : pressure (0 to 127)
  • "controlChange" : controller value (0 to 127)
  • "programChange" : unused
  • "aftertouch" : unused
  • "pitchBend" : unused

myo.midiMachineControl(channel, command)

This functionality is currently only available on Mac OS X.

Send a MIDI Machine Control event through Myo Connect's MIDI interface.

Parameters
channelThe target channel number / device ID, from 0 to 15 inclusive.
commandThe MIDI Machine Control command to send. One of "stop", "play", "deferredPlay", "fastForward", "rewind", "recordStrobe" (Punch in), "recordExit" (Punch out), "recordPause", "pause", "eject", "chase", "MMCReset".

myo.setLockingPolicy(lockingPolicy)

Set the locking policy for the current script.

The locking policy determines how and when Myo locks and unlocks, if at all.

Parameters
lockingPolicyThe new locking policy. Either "none" or "standard".
  • "none" : Don't use any locking mechanism; Myo is always unlocked. With this policy, the myo.unlock() and myo.lock() functions have no effect.
  • "standard" : Use Myo's built-in locking mechanism. This is the default.

myo.unlock(unlockType)

Unlock Myo. Pose events will not be delivered to the script unless Myo is unlocked.

If Myo is locked when this function is called, Myo will vibrate to inform the user that it is now unlocked. If Myo is already unlocked, Myo will remain unlocked, but will not vibrate again. For the "timed" unlockType, the unlock period will be extended. If the current locking policy is "none", this function has no effect.

Parameters
unlockType(Optional) The type of unlock to use. Either "timed" or "hold", with the default being "timed".
  • "timed" : Unlock for a fixed period of time, after which it will automatically re-lock.
  • "hold" : Unlock until a lock() command is explicitly issued.

myo.lock()

Force Myo to re-lock immediately. Pose events will not be delivered while to the script while Myo is locked.

If Myo is unlocked when this function is called, Myo will vibrate to inform the user that it is now locked. If the current locking policy is "none", this function has no effect.

myo.isUnlocked()

Determine whether Myo is currently unlocked.

Returns
true if Myo is currently unlocked, otherwise false.

myo.notifyUserAction()

Notify the connected Myo that a user action was recognized. Will cause Myo to vibrate.