JavaScript API
Use Misty's on-robot JavaScript API to write skills that run locally on your robot. To learn about the architecture of this API, see JavaScript SDK Architecture.
Note: Not all of Misty's API is equally complete. You may see some commands labeled "Beta" or "Alpha" because the related hardware, firmware, or software is still under development. Feel free to use these commands, but realize they may behave unpredictably at this time.
Asset
Misty comes with a set of default images that you can display onscreen and sounds that you can play through her speakers. We encourage you to get creative and use your own image and audio assets in your skills.
misty.DeleteAudio
Enables you to remove an audio file from Misty that you have previously saved. Note: You can only delete audio files that you have saved to Misty. You cannot remove Misty's default system audio files.
// Syntax
misty.DeleteAudio(string fileName, [int prePauseMs], [int postPauseMs]);
Arguments
- fileName (string) - The name of the file to delete, including its file type extension.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.DeleteAudio("DeleteMe.wav");
misty.DeleteImage
Enables you to remove an image file from Misty that you have previously saved to her storage.
Note: You can only delete image files that you have previously saved to Misty's storage. You cannot remove Misty's default system image files.
// Syntax
misty.DeleteImage(string fileName, [int prePauseMs], [int postPauseMs]);
Arguments
- fileName (string) - The name of the file to delete, including its file type extension.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.DeleteImage("DeleteMe.png");
misty.GetAudioFile
Obtains a system or user-uploaded audio file currently stored on Misty.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore (in this case, _GetAudioFile()
). For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
misty.GetAudioFile(string fileName, [string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- fileName (string) - The name of the audio file to get, including its file type extension.
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If blank, the system passes data into the default
_GetAudioFile()
callback function. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetAudioFile("001-EeeeeeE.wav", false);
function _GetAudioFile(data)
{
misty.Debug(JSON.stringify(data));
}
- Result (object) - An object containing audio data and meta information. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
Base64
: A base64-encoded string for the audio file data.ContentType
: The content type of the media encoded in the base64 string.Name
: The filename of the returned audio file.
misty.GetAudioList
Lists all audio files (default system files and user-added files) currently stored on Misty.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetAudioList([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetAudioList();
Returns
- Result (array) - Returns an array of audio file information. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information. Each item in the array contains the following:
- Name (string) - The name of the audio file.
- userAddedAsset (boolean) - If
true
, the file was added by the user. Iffalse
, the file is one of Misty's system files.
misty.GetImage
Obtains a system or user-uploaded image file currently stored on Misty.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
misty.GetImage(string fileName, [string callback], [bool base64 = true], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- fileName (string) - The name of the image file to get, including its file type extension.
- base64 (boolean) - Optional. Passing in
true
returns the image data as a Base64 string. Passing infalse
returns the image. Defaults totrue
. - callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetImage("Angry.png");
function _GetImage(data)
{
misty.Debug(JSON.stringify(data));
}
- Result (object) - An object containing image data and meta information. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
- Name (string) - The name of the image
- Height (integer) - The height of the image in pixels.
- Width (integer) - The width of the image in pixels.
- SystemAsset (boolean) - Whether the image is one of Misty's default image assets.
- ContentType (string) - The type and format of the image returned.
- Base64 (string) - A string containing the Base64-encoded image data.
misty.GetImageList
Obtains a list of the images stored on Misty.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetImageList([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs])
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetImageList();
Returns
- Result (array) - Returns an array containing one element for each image currently stored on Misty. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information. Each element in the array contains the following:
- Height (integer) - The height of the image file.
- Name (string) - The name of the image file.
- Width (integer) - The width of the image file.
- UserAddedAsset (boolean) - If
true
, the file was added by the user. Iffalse
, the file is one of Misty's system files.
misty.SaveAudio
Saves an audio file to Misty. Maximum size is 3 MB. Accepts audio files formatted as .wav
, .mp3
, .wma
, and .aac
.
// Syntax
misty.SaveAudio(string fileName, string data, [bool immediatelyApply], [bool overwriteExisting], [int prePauseMs], [int postPauseMs])
Arguments
- fileName (string) - The name of the audio file.
- data (string) - The audio data, passed as a string containing a base64 string .
- immediatelyApply (boolean) - Optional. A value of
true
tells Misty to immediately play the audio file, while a value offalse
tells Misty not to play the file. - overwriteExisting (boolean) - Optional. A value of
true
indicates the file should overwrite a file with the same name, if one currently exists on Misty. A value offalse
indicates the file should not overwrite any existing files on Misty. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.SaveAudio("Filename.wav", "137,80,78,71,13,1...", false, false);
misty.SaveImage
Saves an image to Misty in the form of a base64 string. Optionally, proportionately reduces the size of the saved image.
Valid image file types are .jpg, .jpeg, .gif, and .png. Maximum file size is 3 MB. Note: Images can be reduced in size but not enlarged. Because Misty does not adjust the proportions of images, for best results use an image with proportions similar to her screen (480 x 272 pixels).
// Syntax
misty.SaveImage(string fileName, string data, [int width], [int height], [bool immediatelyApply], [bool overwriteExisting], [int prePauseMs], [int postPauseMs]
Arguments
- fileName (string) - The name of the image file to save.
- data (string) - The image data, passed as a string containing a base64 string.
- width (integer) - Optional. A whole number greater than 0 specifying the desired image width (in pixels). Important: To reduce the size of an image you must supply values for both
width
andheight
. Note that if you supply disproportionate values forwidth
andheight
, the system uses the proportionately smaller of the two values to resize the image. - height (integer) - Optional. A whole number greater than 0 specifying the desired image height (in pixels). Important: To reduce the size of an image you must supply values for both
width
andheight
. Note that if you supply disproportionate values forwidth
andheight
, the system uses the proportionately smaller of the two values to resize the image. - immediatelyApply (boolean) - Optional. A value of
true
tells Misty to immediately display the saved image file, while a value offalse
tells Misty not to display the image. - overwriteExisting (boolean) - Optional. A value of
true
indicates the saved file should overwrite a file with the same name, if one currently exists on Misty. A value offalse
indicates the saved file should not overwrite any existing files on Misty. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.SaveImage("Filename.jpg", "137,80,78,71,13,1...", 500, 1000, false, false);
Backpack
misty.WriteSerial
Sends data to Misty's universal asynchronous receiver-transmitter (UART) serial port. Use this command to send data from Misty to an external device connected to the port.
Note that Misty can also receive data a connected device sends to the UART serial port. To use this data you must subscribe to SerialMessage
events.
// Syntax
misty.WriteSerial(string message, [int prePauseMs], [int postPauseMs])
Arguments
- message (string) - The data Misty sends to the UART serial port, passed as a string value.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.WriteSerial("your-data");
Event
misty.AddPropertyTest - ALPHA
Creates a property comparison test to specify which data the system sends for a registered event. Use property tests to filter unwanted data out of event messages.
// Syntax
misty.AddPropertyTest(string eventName, string property, string inequality, string valueAsString, string valueType, [int prePauseMs], [int postPauseMs]);
Arguments
- eventName (string) - The name of the event to create a property comparison test for.
- property (string) - The property of the event to compare. For the full list of properties for each event, see the documentation for Misty's different Event Types.
- inequality (string) - The comparison operator to use in the property comparison test, passed as a string. Accepts
"=>"
,"=="
,"!=="
,">"
,"<"
,">="
,"<="
,"exists"
,"empty"
, or"delta"
. - valueAsString (string) - The value of the property to compare against, passed as a string. For the full list of values for each event property, see Event Types.
- valueType (string) - The type of the value specified in
"valueAsString"
. Accepts"double"
,"float"
,"integer"
, "string"
,"datetime"
, or "boolean
" - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.AddPropertyTest("EventName", "SensorPosition", "==", "Back", "string");
misty.AddReturnProperty - ALPHA
Adds an additional return property field for a registered event.
// Syntax
misty.AddReturnProperty(string eventName, string eventProperty, [int prePauseMs], [int postPauseMs]);
Use the misty.AddReturnProperty()
method to add the values of specific properties from an event message to the data object passed to the callback function for the event. When the event callback handles the data object for an event, the data object includes the values of any properties added with misty.AddReturnProperty()
in an array called AdditionalResults
.
You can add multiple return properties to the same event. The order of values in the AdditionalResults
array matches the order in which you added those properties to the event in your skill code. For an example of how this works, see how the following code adds return properties to a BumpSensor
event:
// Add the value of the sensorName and isContacted properties of
// BumpSensor event to the data you want to receive with "Bumped"
// event messages
misty.AddReturnProperty("Bumped", "sensorName");
misty.AddReturnProperty("Bumped", "isContacted");
// Register for BumpSensor events
misty.RegisterEvent("Bumped", "BumpSensor", 50 ,true);
function _Bumped(data) {
// The value of sensorName is at index 0
var sensor = data.AdditionalResults[0]
// The value of isContacted is at index 1
var isContacted = data.AdditionalResults[1]
misty.Debug("Sensor: " + sensor + ", is contacted: " + isContacted)
}
Arguments
- eventName (string) - The name of the event to add a return property field for.
- eventProperty (string) - The additional property to return.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.AddReturnProperty("EventName", "DistanceInMeters");
misty.RegisterEvent - ALPHA
Register to receive messages with live event data from one of Misty's sensors.
Note: Event data must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for this command are given the same name as the correlated event, prefixed with an underscore: _<eventName>
. For more on handling event data, see Sensor Event Callbacks.
// Syntax
misty.RegisterEvent(string eventName, string messageType, int debounce, [bool keepAlive = false], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- eventName (string) - Sets an event name (of your choice) for the registered event. The name of the callback function is set automatically to be the same as your event name, prefixed with an underscore (
_<eventName>
). - messageType (string) - The name of the data stream to register for events from. Matches the predefined
Type
property value for the data stream as listed here. - debounce (integer) - Sets the frequency in milliseconds with which event data is sent.
- keepAlive (boolean) - Optional. Pass
true
to keep the callback function registered to the event after the callback function is triggered. By default, when an event callback is triggered, the event unregisters the callback to prevent more commands from overriding the initial call. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.RegisterEvent("EventName", "TimeOfFlight", 1000, false);
Returns
- Data sent by the registered event. Event data must be passed into a callback function to be processed and made available for use in your skill. For more information, see Sensor Event Callbacks.
misty.RegisterSimpleEvent - ALPHA
Registers for an event and applies a filter to event messages. Events you register for with the misty.RegisterSimpleEvent()
command only return messages for events that pass the property comparison test you specify in the command's arguments.
// Syntax
misty.RegisterSimpleEvent(string eventName, string messageType, int debounce, [bool keepAlive = false], [string property], [string inequality], [string valueAsString], [string valueType], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- eventName (string) - Sets an event name (of your choice) for the registered event. The name of the callback function is set automatically to be the same as your event name, prefixed with an underscore (
_<eventName>
). - messageType (string) - The name of the data stream to register for events from. Matches the predefined
Type
property value for the data stream as listed here. - debounce (integer) - Sets the frequency in milliseconds with which event data is sent.
- keepAlive (boolean) - Optional. Pass
true
to keep the callback function registered to the event after the callback function is triggered. By default, when an event callback is triggered, the event unregisters the callback to prevent more commands from overriding the initial call. - property (string) - The property of the event to compare. For the full list of properties for each event, see Event Types.
- inequality (string) - The comparison operator to use in the property comparison test, passed as a string. Accepts
"=>"
,"=="
,"!=="
,">"
,"<"
,">="
,"<="
,"exists"
,"empty"
, or"delta"
. - valueAsString (string) - The value of the property to compare against, passed as a string. For the full list of values for each event property, see Event Types.
- valueType (string) - The type of the value specified in
"valueAsString"
. Accepts"double"
,"float"
,"integer"
, "string"
,"datetime"
, or "boolean
" - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
Returns
- Data sent by the registered event. Event data must be passed into a callback function to be processed and made available for use in your skill. For more information, see Sensor Event Callbacks.
misty.RegisterTimerEvent - ALPHA
Creates an event that calls a callback function after a specified period of time. For an example of using this function, see the Timer Event tutorial.
Note: Event data must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for this command are given the same name as the correlated event, prefixed with an underscore: _<eventName>
. For more on handling event data, see Timed or Triggered Event Callbacks.
// Syntax
misty.RegisterTimerEvent(string eventName, int callbackTimeInMs, [bool keepAlive], [string callbackRule], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- eventName (string) - The name for the timer event. Note that the name you give to this timer event determines the name automatically assigned to your related callback function. That is, the system sets the name of the callback function to be the same as this event name, prefixed with an underscore (
_<eventName>
). For example, for an event name ofMyTimerEvent
, your callback function must use the name_MyTimerEvent
. - callbackTimeInMs (integer) - The amount of time in milliseconds to wait before the system calls the callback function. For example, passing a value of 3000 causes the system to wait 3 seconds.
- keepAlive (boolean) - Optional. By default (
false
) this timer event calls your callback only once. If you passtrue
, your callback function is called in a loop, with a frequency determined bycallbackTimeInMs
. To end the loop, call themisty.UnregisterEvent()
function in your code. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.RegisterTimerEvent("EventName", 5000, false);
Returns
- Data sent by the timed event. Event data must be passed into a callback function to be processed and made available for use in your skill. For more information, see Timed or Triggered Event Callbacks.
misty.RegisterUserEvent - ALPHA
Creates an event that calls a callback function at a point of your choosing. You trigger the event by making a REST call to the <robot-ip-address>/api/skills/event
endpoint with the appropriate payload for the callback and/or skill.
Once you register the event with misty.RegisterUserEvent()
, to trigger the event you must make a REST call to the event endpoint with a POST command:
POST <robot-ip-address>/api/skills/event
With a JSON body similar to:
{
"UniqueId" : "b307c917-beb8-47e8-9bbf-1c57e8cd4d4b",
"EventName": "UserEventName",
"Payload": { "mydata": "two" }
}
The UniqueId
and EventName
values are required and must match the ID of the skill to call and the event name you used in that skill. You should place any payload data you wish to send to the skill in the Payload
field.
Note: Event data must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for this command are given the same name as the correlated event, prefixed with an underscore: _<eventName>
. For more on handling event data, see Timed or Triggered Event Callbacks.
// Syntax
misty.RegisterUserEvent(string eventName, [bool keepAlive], [string callbackRule], [string skillToCall], [int prePauseMs], [int postPauseMs])
Arguments
- eventName (string) - The name for the event. Note that the name you give to this event determines the name automatically assigned to your related callback function. That is, the system sets the name of the callback function to be the same as this event name, prefixed with an underscore (
_<eventName>
). For example, for an event name ofMyUserEvent
, your callback function must use the name_MyUserEvent
. - keepAlive (bool) - Optional. By default (
false
) the event is triggered only once. If you passtrue
, you can trigger the event repeatedly. To remove this event, call themisty.UnregisterEvent()
function in your code. - callbackRule (string) - Optional. By default (
Synchronous
) the system runs the triggered callback concurrently with any other running threads. Other values areOverride
andAbort
.Override
tells the system to run the new callback thread but to stop running commands on any other threads, including the thread the callback was called within. The system only runs the thread the callback was triggered in, once the callback comes back.Abort
tells the system to ignore the new callback thread if the skill is still doing work on any other threads (including the original thread the callback was called within). - skillToCall (string) - Optional. The unique ID of a skill to call when the event is triggered. Use this value if the callback function is not defined in the same skill as the user event is registered in.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.RegisterUserEvent("EventName", false);
Returns
- Data sent by the user event. Event data must be passed into a callback function to be processed and made available for use in your skill. For more information, see Timed or Triggered Event Callbacks.
misty.UnregisterAllEvents - ALPHA
Unregisters from all events for the skill in which this command is called.
// Syntax
misty.UnregisterAllEvents([int prePauseMs], [int postPauseMs])
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.UnregisterAllEvents();
misty.UnregisterEvent - ALPHA
Unregisters from a specified event.
// Syntax
misty.UnregisterEvent(string eventName, [int prePauseMs], [int postPauseMs]);
Arguments
- eventName (string) - The name of the event to unregister from.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.UnregisterEvent("EventName");
Expression
misty.ChangeLED
Changes the color of the LED light behind the logo on Misty's torso.
// Syntax
misty.ChangeLED(int red, int green, int blue, [int prePauseMs], [int postPauseMs]);
Arguments
- Red (integer) - A value between 0 and 255 specifying the red RGB color.
- Green (integer) - A value between 0 and 255 specifying the green RGB color.
- Blue (integer) - A value between 0 and 255 specifying the blue RGB color.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.ChangeLED(0, 0, 0);
misty.DisplayImage
Displays an image on Misty's screen. Optionally, misty.DisplayImage()
can display an image for a specific length of time and/or transparently overlay an image on Misty's eyes. You can use the SaveImage
command in Misty's REST API to upload images to Misty.
Note that it's not possible for a custom image to overlay another custom image. Misty's eyes always appear as the base image, behind an overlay.
// Syntax
misty.DisplayImage(string fileName, [double alpha], [int prePauseMs], [int postPauseMs])
Arguments
- fileName (string) - Name of the file containing the image to display. Valid image file types are .jpg, .jpeg, .gif, .png. Maximum file size is 3MB. To clear the image from the screen, pass an empty string
""
. - alpha (double) - Optional. The transparency of the image. A value of 0 is completely transparent; 1 is completely opaque. When you specify a value greater than 0 and less than 1, the image appears but is transparent, and Misty's eyes appear behind the specified image. Defaults to 1.
- prePauseMsMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.DisplayImage("e_Amazement.jpg");
misty.PlayAudio
Plays an audio clip that has been previously saved to Misty's storage.
// Syntax
misty.PlayAudio(string fileName, [int volume], [int prePauseMs], [int postPauseMs]);
Arguments
- fileName (string) - The name of the file to play.
- volume (integer) - Optional. A value between 0 and 100 for the loudness of the audio clip. 0 is silent, and 100 is full volume. By default, the system volume is set to 100.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.PlayAudio("s_Sadness.wav", 100);
misty.SetFlashlight
Turns the LED flashlight on Misty's head on or off.
// Syntax
misty.SetFlashlight(bool on, [int prePauseMs], [int postPauseMs]);
Parameters
- on (bool) - Turns the flashlight on (
true
) or off (false
).
// Example
misty.SetFlashlight(true);
misty.SetBlinking - BETA
Turns Misty's eye blinking behavior on or off.
// Syntax
misty.SetBlinking(bool blink, [int prePauseMs], [int postPauseMs]);
Note: To customize Misty's blinking behavior, use the SetBlinkSettings
command in Misty's REST API.
Misty stops blinking when there is an error message on her screen, and starts blinking again when the message clears.
Arguments
- blink (bool) - Passing in
true
turns blinking on, and passing infalse
turns blinking off. By default, blinking turns on when Misty starts up. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.SetBlinking(true);
External Requests
misty.SendExternalRequest - ALPHA
Sends an HTTP request from Misty to an external server. You use misty.SendExternalRequest()
to access resources that are available via Uniform Resource Identifiers (URIs), such as cloud-based APIs or data stored on a server in another location.
Note: In most cases, the external server's response to requests sent from the robot must be passed into a callback function to be processed and made available for use in your skills. By default, the callback function for this command is given the same name as the command, prefixed with an underscore: _SendExternalRequest()
. For more on handling data returned by misty.SendExternalRequest()
, see the External Requests tutorial.
// Syntax
misty.SendExternalRequest(string method, string resourceURL, [string authorizationType], [string token], [string arguments], [bool save], [bool apply], [string fileName], [string contentType], [string callback], [string callbackRule], [string skillToCal], [int prePauseMs], [int postPauseMs]);
Arguments
- method (string) - The HTTP request method (e.g.
GET
,POST
, etc.) indicating the action to perform for the resource. - resource (string) - The full Uniform Resource Identifier of the resource, i.e.
"http://soundbible.com/grab.php?id=1949&type=mp3"
. - authorizationType (string) - Optional. The authentication type required to access the resource, i.e.
"OAuth 1.0"
,"OAuth 2.0"
, or"Bearer Token"
. Usenull
if no authentication is required. - token (string) - Optional. The authentication credentials required to access the resource. Use
null
if no credentials are required. - arguments (string) - Optional. The arguments to send with the request, passed as a string written in JSON format with key-value pairs for each parameter option. If the request does not require additional arguments, pass
null
or an empty JSON string ("{}"
). - save (bool) - Optional. If
true
, the robot saves any media asset contained in the request response to the robot's local storage. If you do not want to save any returned assets, passfalse
. At this time, themisty.SendExternalRequest()
command can save only image and audio files to Misty. - apply (bool) - Optional. A value of
true
orfalse
indicating whether to immediately use a media asset once it has been saved to Misty's local storage. Usetrue
to immediately play an audio asset or display an image asset on Misty's screen. Note that to successfully apply a media asset, you must also passtrue
for thesaveAssetToRobot
parameter. - fileName (string) - Optional. The name to give the saved file, including the appropriate file type extension.
- contentType (string) - Optional. The content type of the data you are sending with the request. Defaults to
"application/json"
. - callback (string) - Optional. The name of the callback function to call when the returned data is received. If empty, a callback function with the default name (
_SendExternalRequest()
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of the skill to trigger for the callback function, if the callback is not defined in the current skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
Returns
- Data (object) - An object containing the external server's response to the request. In most cases, data returned by the
misty.SendExternalRequest()
command must be passed into a callback function to be processed and made available for use in your skills. See the External Requests tutorial for more information.
Movement
misty.Drive
Drives Misty forward or backward at a specific speed until cancelled. Call misty.Stop()
to cancel driving.
When using the misty.Drive()
command, it helps to understand how linear velocity (speed in a straight line) and angular velocity (speed and direction of rotation) work together:
- Linear velocity (-100) and angular velocity (0) = driving straight backward at full speed.
- Linear velocity (100) and angular velocity (0) = driving straight forward at full speed.
- Linear velocity (0) and angular velocity (-100) = rotating clockwise at full speed.
- Linear velocity (0) and angular velocity (100) = rotating counter-clockwise at full speed.
- Linear velocity (non-zero) and angular velocity (non-zero) = Misty drives in a curve.
// Syntax
misty.Drive(double linearVelocity, double angularVelocity, [int prePauseMs], [int postPauseMs]);
Arguments
- linearVelocity (double) - A percent value that sets the speed for Misty when she drives in a straight line. Default value range is from -100 (full speed backward) to 100 (full speed forward).
- angularVelocity (double) - A percent value that sets the speed and direction of Misty's rotation. Default value range is from -100 (full speed rotation clockwise) to 100 (full speed rotation counter-clockwise). Note: For best results when using angular velocity, we encourage you to experiment with using small positive and negative values to observe the effect on Misty's movement.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.Drive(0, 0);
misty.DriveTime
Drives Misty forward or backward at a set speed, with a given rotation, for a specified amount of time.
When using the misty.DriveTime()
command, it helps to understand how linear velocity (speed in a straight line) and angular velocity (speed and direction of rotation) work together:
- Linear velocity (-100) and angular velocity (0) = driving straight backward at full speed.
- Linear velocity (100) and angular velocity (0) = driving straight forward at full speed.
- Linear velocity (0) and angular velocity (-100) = rotating clockwise at full speed.
- Linear velocity (0) and angular velocity (100) = rotating counter-clockwise at full speed.
- Linear velocity (non-zero) and angular velocity (non-zero) = Misty drives in a curve.
// Syntax
misty.DriveTime(double linearVelocity, double angularVelocity, int timeMs, [double degree], [int prePauseMs], [int postPauseMs]);
Arguments
- linearVelocity (double) - A percent value that sets the speed for Misty when she drives in a straight line. Default value range is from -100 (full speed backward) to 100 (full speed forward).
- angularVelocity (double) - A percent value that sets the speed and direction of Misty's rotation. Default value range is from -100 (full speed rotation clockwise) to 100 (full speed rotation counter-clockwise). Note: For best results when using angular velocity, we encourage you to experiment with using small positive and negative values to observe the effect on Misty's movement.
- timeMs (integer) - A value in milliseconds that specifies the duration of movement. Misty will not drive if you pass in a value of less than 100 for this argument.
- degree (double) - (optional) The number of degrees to turn. Note: Supplying a
degree
value recalculates linear velocity. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.DriveTime(0, 0, 0);
misty.DriveTrack
Drives Misty left, right, forward, or backward, depending on the track speeds specified for the individual tracks.
// Syntax
misty.DriveTrack(double leftTrackSpeed, double rightTrackSpeed, [int prePauseMs], [int postPauseMs])
Arguments
- leftTrackSpeed (double) - A value for the speed of the left track, range: -100 (full speed backward) to 100 (full speed forward).
- rightTrackSpeed (double) - A value for the speed of the right track, range: -100 (full speed backward) to 100 (full speed forward).
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.DriveTrack(0, 0);
misty.Halt
Stops all motor controllers, including drive motor, head/neck, and arm.
// Syntax
misty.Halt([int prePauseMs], [int postPauseMs])
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.Halt();
misty.MoveArm
Moves one or both of Misty's arms.
Parameters
- arm (string) - The arm to move. You must use either
left
,right
, orboth
. - position (integer) - The new position to move the arm to. Expects a value of 0 - 10. 5 Points the arms straight forward.
- velocity (integer) - Optional. A value of 0 to 100, specifying the speed with which the arm should move.
- duration (integer) - Unused at this time. Can use
null
or0
. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveArm("both", 0, 100);
misty.MoveArms
Moves one or both of Misty's arms. You can use this command to control both arms simultaneously or one at a time.
Parameters
- leftArmPosition (double) - Optional. The new position of Misty's left arm. Expects a value of 0-10. 5 points forward, directly in front of the robot.
- rightArmPosition (double) - Optional. The new position of Misty's right arm. Expects a value of 0-10. 5 points forward, directly in front of the robot.
- leftArmVelocity (double) - Optional. A value of 0 to 100 specifying the speed with which the left arm should move.
- rightArmVelocity (double) - Optional. A value of 0 to 100, specifying the speed with which the right arm should move.
- duration (integer) - Unused at this time. Can use
null
or0
. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveArms(0, 0, 100, 100);
misty.MoveArmPosition
Moves one of Misty's arms to a specified position.
// Syntax
misty.MoveArmPosition(string arm, double position, double velocity, [int prePauseMs], [int postPauseMs])
Arguments
- arm (string) - The arm to move. Use
left
,right
, orboth
. - position (double) - The position to move the arm to. Expects a value of 0-10. 5 points forward, directly in front of the robot.
- velocity (double) - The velocity with which to move the arm. Velocity value is a percentage of maximum velocity. Value range: 0 - 100.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveArmPosition("left", 0, 10);
misty.MoveArmDegrees
Moves one of Misty's arms to a specified location in degrees.
When moving Misty's arms, it's helpful to understand their orientation.
- At 0 degrees, Misty's arms point straight forward along her X axis, parallel to the ground.
- At +90 degrees, Misty's arms point straight down towards the ground.
- At +/- 180 degrees, Misty's arms would face straight back, pointing toward her backpack. Currently, Misty's arms are not configured to move to this position.
- At +270/-90 degrees, Misty's arms point straight up towards her head, and are perpendicular to the ground. Currently, the upward limit of Misty's arm movement is -29 degrees.
// Syntax
misty.MoveArmDegrees(string arm, double degrees, double velocity, [int prePauseMs], [int postPauseMs])
Arguments
- arm (string) - The arm to move. Use
left
,right
, orboth
. - degrees (double) - The location in degrees to move the arm to. Value range: 0 to -180.
- velocity (double) - The velocity with which to move the arm. Velocity value is a percentage of maximum velocity. Value range: 0 - 100.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveArmDegrees("right", -90, 50);
misty.MoveArmRadians
Moves one of Misty's arms to a specified location in radians.
// Syntax
misty.MoveArmRadians(string arm, double radians, double velocity, [int prePauseMs], [int postPauseMs])
Arguments
- arm (string) - The arm to move. Use
left
,right
, orboth
. - radians (double) - The position in
radians
to move the arm to. - velocity (double) - The velocity with which to move the arm. Velocity value is a percentage of maximum velocity. Value range: 0 - 100.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveArmRadians("left", -1.5708, 50);
misty.MoveHead
Moves Misty's head in one of three axes (tilt, turn, or up-down).
Value Ranges for Each Axis of Movement
position | |
---|---|
pitch | -5 (up) to 5 (down) |
roll | -5 (left) to 5 (right) |
yaw | -5 (right) to 5 (left) |
Arguments
- pitch (double) - Value that determines the up or down movement of Misty's head movement.
- roll (double) - Value that determines the tilt ("ear" to "shoulder") of Misty's head. Misty's head will tilt to the left or right.
- yaw (double) - Number that determines the turning of Misty's head. Misty's head will turn left or right.
- velocity (double) - Optional. The percentage of max velocity that indicates how quickly Misty should move her head. Value range: 0 to 100. Defaults to 10.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Misty looks straight ahead
misty.MoveHead(0, 0, 0, 100);
misty.MoveHeadDegrees
Moves Misty's head in one of three axes (tilt, turn, or up-down). Note: For Misty I, the misty.MoveHeadDegrees()
command can only control the up-down movement of Misty's head.
// Syntax
misty.MoveHeadDegrees(double pitch, double roll, double yaw, double velocity, [int prePauseMs], [int postPauseMs]);
Arguments
- pitch (double) - A value specifying the position of Misty’s head along the up-down axis. Values range from approximately -40 (fully up) to 26 (fully down). Note that due to normal variations in the range of head motion available to each robot, the minimum and maximum values for your Misty may differ slightly from the values listed here.
- roll (double) - A value specifying the tilt ("ear" to "shoulder") of Misty’s head. Misty’s head tilts to the left or right. Values range from -40 (fully left) to 40 (fully right). Note that due to normal variations in the range of head motion available to each robot, the minimum and maximum values for your Misty may differ slightly from the values listed here. This value is ignored for Misty I.
- yaw (double) - A value specifying the turn to the left or right of Misty’s head. Values range from -81 (fully right) to 81 (fully left). Note that due to normal variations in the range of head motion available to each robot, the minimum and maximum values for your Misty may differ slightly from the values listed here. This value is ignored for Misty I.
- velocity (double) - Number that represents speed at which Misty moves her head. Value range: 0 to 100.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveHeadDegrees(10, 10, 10, 100);
misty.MoveHeadPosition
Moves Misty's head in one of three axes (tilt, turn, or up-down). Note: For Misty I, the misty.MoveHeadPosition()
command can only control the up-down movement of Misty's head.
// Syntax
misty.MoveHeadPosition(double pitch, double roll, double yaw, double velocity, [int prePauseMs], [int postPauseMs]);
Arguments
- pitch (double) - A value specifying the position of Misty’s head along the up-down axis. Values range from -5 (fully up) to 5 (fully down).
- roll (double) - A value specifying the tilt ("ear" to "shoulder") of Misty’s head. Values range from -5 (head tilted fully to the left shoulder) to 5 (head fully to the right shoulder). This value is ignored for Misty I.
- yaw (double) - A value specifying the turn to the left or right of Misty’s head. Values range from -5 (fully right) to 5 (fully left). This value is ignored for Misty I.
- velocity (double) - A value from 0 to 100 specifying the speed at which Misty moves her head.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveHeadPosition(0, 0, 0, 100);
misty.MoveHeadRadians
Moves Misty's head in one of three axes (tilt, turn, or up-down). Note: For Misty I, the MoveHeadPosition
command can only control the up-down movement of Misty's head.
// Syntax
misty.MoveHeadRadians(double pitch, double roll, double yaw, double velocity, [int prePauseMs], [int postPauseMs]);
Arguments
- pitch (double) - A value in radians specifying the position of Misty’s head along the up-down axis. Values range from -0.1662 (fully up) to 0.6094 (fully down). Note that due to normal variations in the range of head motion available to each robot, the minimum and maximum values for your Misty may differ slightly from the values listed here.
- roll (double) - A value in radians specifying the tilt ("ear" to "shoulder") of Misty’s head. Values range from -0.75 (head tilted fully to the left shoulder) to 0.75 (head fully to the right shoulder). Note that due to normal variations in the range of head motion available to each robot, the minimum and maximum values for your Misty may differ slightly from the values listed here. This value is ignored for Misty I.
- yaw (double) - A value in radians specifying the turn to the left or right of Misty’s head. Values range from -1.57 (fully right) to 1.57 (fully left). Note that due to normal variations in the range of head motion available to each robot, the minimum and maximum values for your Misty may differ slightly from the values listed here. This value is ignored for Misty I.
- velocity (double) - Number that represents speed at which Misty moves her head. Value range: 0 to 10.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.MoveHeadRadians(0.5708, 0.5708, 1.5708, 100);
misty.Stop
Stops Misty's movement.
// Syntax
misty.Stop([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.Stop();
misty.DriveArc - ALPHA
Drives Misty in an arc. Misty continues driving until her current heading matches the desired absolute heading passed into this command.
Misty's velocity is equal to:
((desired_heading - current_heading) * (π/180) * radius) / (timeMs/1000)
.
Misty's maximum angular velocity will not exceed 45 degrees per second, and her maximum linear velocity will not exceed 1 meter per second.
To get Misty's current heading, use the value for yaw
from the IMU
named object.
// Syntax
misty.DriveArc(double heading, double radius, double timeMs, [bool reverse], [int prePauseMs], [int postPauseMs])
Arguments
- heading (double) - The absolute heading Misty should obtain when the arc is complete. To set the absolute heading, use either: 0 - 360, where 0 is straight ahead, 90 is directly to the left, 180 is straight behind, and 270 is directly to the right, or: -180 to 180, where 0 is straight ahead, 90 is directly to the left, 180 and -180 are straight behind, and -90 is directly to the right.
- radius (double) - The radius (in meters) of the arc.
- timeMs (double) - The duration (in milliseconds) that Misty drives.
- reverse (boolean) - Optional. If
true
, Misty drives in reverse. Default isfalse
. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
// Misty drives in an arc with a 1m radius for 5
// seconds to obtain an absolute heading of 180 degrees
misty.DriveArc(180, 1, 5000, false)
misty.DriveHeading - ALPHA
Drives Misty forward or backward in a straight line. While driving, Misty continuously adjusts her current heading to maintain the desired absolute heading.
For a smooth driving experience, Misty's current heading should be within two degrees of the desired absolute heading before she executes the misty.DriveHeading()
command. A variation of greater than two degrees results in large correction velocities. You can use the misty.DriveArc()
command to face Misty in the direction of the heading you want her to maintain. Then, use the misty.DriveHeading()
command to drive Misty forward or backward in a straight line.
To get Misty's current heading, use the value for yaw
from the IMU
named object.
Note: Misty's velocity is equal to distance / (timeMs/1000)
. Misty's maximum angular velocity will not exceed 45 degrees per second, and her maximum linear velocity will not exceed 1 meter per second.
// Syntax
misty.DriveHeading(double heading, double distance, double timeMs, [bool reverse], [int prePauseMs], [int postPauseMs])
Arguments
- heading (double) - The absolute heading Misty should maintain. To set the absolute heading, use either: 0 - 360, where 0 is straight ahead, 90 is directly to the left, 180 is straight behind, and 270 is directly to the right, or: -180 to 180, where 0 is straight ahead, 90 is directly to the left, 180 and -180 are straight behind, and -90 is directly to the right.
- distance (double) - The distance (in meters) that Misty should drive.
- timeMs (double) - The duration (in milliseconds) that Misty should drive.
- reverse (boolean) - Optional. If
true
, Misty drives in reverse. Default isfalse
. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
// Misty drives forward 0.5m over 4 seconds and
// maintains an absolute heading of 90 degrees
misty.DriveHeading(90, 0.5, 4000, false);
Navigation
"SLAM" refers to simultaneous localization and mapping. This is a robot's ability to both create a map of the world and know where they are in it at the same time. Misty's SLAM capabilities and hardware are under development. For a step-by-step mapping exercise, see the instructions with the Command Center.
Note: Misty’s SLAM capabilities are an alpha feature. Experiment with mapping, but recognize that Misty’s ability to create maps and track within them is unreliable at this time.
misty.StartSlamStreaming
Opens the data stream from the Occipital Structure Core depth sensor, so you can obtain image and depth data when Misty is not actively tracking or mapping.
Important! Always use misty.StopSlamStreaming()
to close the depth sensor data stream after sending commands that use Misty's Occipital Structure Core depth sensor. Calling misty.StopSlamStreaming()
turns off the laser in the depth sensor and lowers Misty's power consumption.
// Syntax
misty.StartSlamStreaming([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartSlamStreaming();
misty.StopSlamStreaming
Closes the data stream from the Occipital Structure Core depth sensor. Calling this command turns off the laser in the depth sensor and lowers Misty's power consumption.
Important! Always use this command to close the depth sensor data stream after using misty.StartSlamStreaming()
and any commands that use Misty's Occipital Structure Core depth sensor. Note that Misty's 4K camera may not work while the depth sensor data stream is open.
// Syntax
misty.StopSlamStreaming([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this
command,
postPauseMs
is not used.
// Example
misty.StopSlamStreaming();
misty.TakeDepthPicture
Provides the current distance of objects from Misty’s Occipital Structure Core depth sensor. Note that depending on the scene being viewed, the sensor may return a large proportion of "unknown" values in the form of NaN
("not a number") values.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.TakeDepthPicture([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
_<COMMAND>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.TakeDepthPicture();
Returns
- Result (object) - An object containing depth information about the image matrix, with the following fields. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
- height (integer) - The height of the matrix.
- image (array) - A matrix of size
height
xwidth
containing individual values of type float. Each value is the distance in millimeters from the sensor for each pixel in the captured image. For example, if you point the sensor at a flat wall 2 meters away, most of the values in the matrix should be around 2000. Note that as the robot moves further away from a scene being viewed, each pixel value will represent a larger surface area. Conversely, if it moves closer, each pixel value will represent a smaller area. - width (integer) - The width of the matrix.
misty.TakeFisheyePicture
Takes a photo using the camera on Misty’s Occipital Structure Core depth sensor.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.TakeFisheyePicture([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs])
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
_<COMMAND>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.TakeFisheyePicture();
Returns
- Result (object) - An object containing image data and meta information. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
- base64 (string) - A string containing the Base64-encoded image data.
- contentType (string) - The type and format of the image returned.
- height (integer) - The height of the picture in pixels.
- name (string) - The name of the picture.
- width (integer) - The width of the picture in pixels.
misty.FollowPath - ALPHA
Drives Misty on a path defined by coordinates you specify. Note that Misty must have a map and be actively tracking before starting to follow a path. Misty will not be able to successfully follow a path if unmapped obstacles are in her way.
Note: Make sure to call misty.StartTracking()
to start Misty tracking her location before using this command, and call misty.StopTracking()
to stop Misty tracking her location after using this command.
// Syntax
misty.FollowPath(string path, [int prePauseMs], [int postPauseMs]);
Arguments
- path (string) - A string of comma-separated X:Y coordinates representing waypoints on a path for Misty to track through her currently active map. Each waypoint is a colon-separated integer pair representing the X and Y coordinates of a location on Misty's currently active map. You can use the
GetMap
command in Misty's REST API to access the occupancy grid for Misty's current map, and use this grid to determine the X and Y coordinates of the destination. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.FollowPath("4:3,8:8,10:15");
misty.GetMap - ALPHA
Obtains the occupancy grid data for Misty's currently active map.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
Note: To obtain a valid response from misty.GetMap()
, Misty must first have successfully generated a map. To change the currently active map, use the SetCurrentSlamMap
command in Misty's REST API.
Misty’s maps are squares that are constructed around her initial physical location when she starts mapping. When a map is complete, it is a square with Misty’s starting point at the center.
The occupancy grid for the map is represented by a two-dimensional matrix. Each element in the occupancy grid represents an individual cell of space. The value of each element (0, 1, 2, or 3) indicates the nature of the space in those cells (respectively: "unknown", "open", "occupied", or "covered").
Each cell corresponds to a pair of X,Y coordinates that you can use with the misty.FollowPath()
, misty.DriveToLocation()
, and misty.GetSlamPath()
commands. The first cell in the first array of the occupancy grid is the origin point (0,0) for the map. The X coordinate of a given cell is the index of the array for the cell. The Y coordinate of a cell is the index of that cell within its array.
// Syntax
misty.GetMap([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetMap();
Returns
- Result (object) - An object containing the following key-value pairs. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
- grid (array of arrays) - The occupancy grid for the most recent map Misty has generated, represented by a matrix of cells. The number of arrays is equal to the value of the
height
parameter. The number of cells is equal to the product ofheight
xwidth
. Each individual value (0, 1, 2, or 3) in the matrix represents a single cell of space. 0 indicates "unknown" space, 1 indicates "open" space, 2 indicates "occupied" space, and 3 indicates "covered" space. Each cell corresponds to an X,Y coordinate on the occupancy grid. The first cell in the first array is the X,Y origin point (0,0) for the map. The X coordinate of a given cell is the index of the array for the cell. The Y coordinate of a cell is the index of that cell within its array. If no map is available, grid returnsnull
. - height (integer) - The height of the occupancy grid matrix (in number of cells).
- isValid (boolean) - Returns a value of
true
if the data returned represents a valid map. If no valid map data is available, returns a value offalse
. - metersPerCell (integer) - A value in square meters stating the size of each cell in the occupancy grid matrix.
- originX (float) - The distance in meters from the X value of the occupancy grid origin (0,0) to the X coordinate of the physical location where Misty started mapping. The X,Y coordinates of Misty's starting point are always at the center of the occupancy grid. To convert this value to an X coordinate on the occupancy grid, use the formula 0 - (
originX
/metersPerCell
). Round the result to the nearest whole number. - originY (float) - The distance in meters from the Y value of the occupancy grid origin (0,0) to the Y coordinate of the physical location where Misty started mapping. The X,Y coordinates of Misty's starting point are always at the center of the occupancy grid. To convert this value to a Y coordinate on the occupancy grid, use the formula 0 - (
originY
/metersPerCell
). Round the result to the nearest whole number. - size (integer) - The total number of map cells represented in the grid array. Multiply this number by the value of meters per cell to calculate the area of the map in square meters.
- width (integer) - The width of the occupancy grid matrix (in number of cells).
- grid (array of arrays) - The occupancy grid for the most recent map Misty has generated, represented by a matrix of cells. The number of arrays is equal to the value of the
misty.GetSlamPath - ALPHA
Obtain a path from Misty’s current location to a specified set of X,Y coordinates. Pass the waypoints this command returns to the path
parameter of misty.FollowPath()
for Misty to follow this path to the desired location.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
Important! Make sure to call misty.StartTracking()
to start Misty tracking her location before using this command, and call misty.StopTracking()
to stop Misty tracking her location after using this command.
// Syntax
misty.GetSlamPath(double X, double Y, [string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- X (double) - The X coordinate of the destination.
- Y (double) - The Y coordinate of the destination.
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetSlamPath(100, 250);
Returns
- Result (array) - An array containing integer pairs. Each pair specifies the X,Y coordinates for a waypoint on the path. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
misty.GetSlamStatus - ALPHA
Obtains values representing the current activity and status of Misty's SLAM system. Check these values for information about the current status of Misty's depth sensor, the SLAM system, and to see information relevant to any ongoing mapping or tracking activities.
Note: We suggest primarily using the values of Status
/StatusList
when coding SLAM functionality in your skills and robot applications, and only using the SensorStatus
and RunMode
values as supplemental information if needed or for debugging purposes.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _GetSlamStatus()
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetSlamStatus([string callback], [string callbackRule], [string skillToCall], [int prePauseMs], [int postPauseMs])
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
_GetSlamStatus()>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetSlamStatus();
Returns
- Result (object) - A data object with the following key-value pairs. Note: With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
status
(int) - Number that describes the current status of the SLAM system. This number updates with information from thesensorStatus
andrunMode
fields, as well as with other events that occur during a SLAM session. Note that this number represents several status codes simultaneously. You can convert this number to a binary value to see whether the bit field for a given status code is on (1
) or off (0
). As an example, the status code33028
converts to a binary value of1000000100000100
. In this binary value, the 3rd, 9th, and 16th bits are flipped. Those bits correspond to the status codes forExploring
,LostPose
, andStreaming
, respectively. (Note that the system also returns the string fields for all current status codes to thestatusList
array that comes back with aGetSlamStatus
response.) The following hexadecimal values correspond to bit fields for each possible status code:- 0x0000:
Uninitialized
- The SLAM system is not yet initialized. - 0x0001:
Initializing
- The SLAM system is initializing. - 0x0002:
Ready
- Misty's depth sensor and the SLAM system are ready to start mapping and tracking. - 0x0004:
Exploring
- The SLAM system is mapping. - 0x0008:
Tracking
- The SLAM system is tracking. - 0x0010:
Recording
- The SLAM system is recording an.occ
file to Misty's local storage. - 0x0020:
Resetting
- The SLAM system is in the process of shutting down and resetting. - 0x0040:
Rebooting
- The SLAM system is rebooting. - 0x0080:
HasPose
- The SLAM system has obtained pose. - 0x0100:
LostPose
- The SLAM system has lost pose after having obtained it. - 0x0200:
Exporting_Map
- The SLAM system is exporting a map after mapping is complete. - 0x0400:
Error
- There is an error with the SLAM system or with the depth sensor. - 0x0800:
Error_Sensor_Not_Connected
- The depth sensor is not connected. - 0x1000:
Error_Sensor_No_Permission
- The system does not have permission to use the depth sensor. - 0x2000:
Error_Sensor_Cant_Open
- The system cannot open the depth sensor for communication. - 0x4000:
Error_Error_Power_Down_Robot
- Unrecoverable error. Power down the robot and restart. - 0x8000:
Streaming
- The SLAM system is streaming.
- 0x0000:
statusList
(array) - A list of the string values that describe the current status of the SLAM system. Can contain any of the values represented by thestatus
field.runMode
(string) - Current status of the navigation system. Possible values are:Uninitialized
Tracking
Exploring
Relocalizing
Paused
ExportingScene
NeedMoreMotionToInitMap
NotAvailable
sensorStatus
(string) - Current status of the depth sensor sensor. Possible values are:Uninitialized
Connected
Booting
Ready
Disconnected
Error
USBError
LowPowerMode
RecoveryMode
ProdDataCorrupt
CalibMissingOrInvalid
FWVersionMismatch
FWUpdate
FWUpdateComplete
FWUpdateFailed
FWCorrupt
EndOfFile
USBDriverNotInstalled
Streaming
misty.ResetSlam - ALPHA
Resets Misty's SLAM sensors.
// Syntax
misty.ResetSlam([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.ResetSlam();
misty.StartMapping - ALPHA
Starts Misty mapping an area.
Misty saves each map she creates to local storage. Each map is associated with a unique key at the time of the map's creation. Map keys are formatted as date timestamps in UTC (i.e. Map_20190911_21.47.16.UTC
). To obtain a list of Misty's existing maps, use the GetSlamMaps
command in Misty's REST API.
Note: Misty's SLAM system can run out of memory, especially while mapping mapping large, complex areas. When this happens, the SLAM system shuts down, and Misty saves any progress made on the current map to her local storage.
// Syntax
misty.StartMapping([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartMapping();
misty.StartTracking - ALPHA
Starts Misty tracking her location.
// Syntax
misty.StartTracking([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartTracking();
misty.StopMapping - ALPHA
Stops Misty mapping an area.
// Syntax
misty.StopMapping([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this
command,
postPauseMs
is not used.
// Example
misty.StopMapping();
misty.StopTracking - ALPHA
Stops Misty tracking her location.
// Syntax
misty.StopTracking([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StopTracking();
Perception
The following commands allow you to programmatically take pictures, record sounds or videos, and have misty detect and learn to recognize faces.
Like most of us, Misty sees faces best in a well-lit area. If you want to directly experiment with face recognition commands, you can use the Command Center.
To programmatically obtain live data streams back from Misty that include face detection and recognition data, you can subscribe to her FaceRecognition WebSocket. To directly observe this data, you can use the Command Center.
misty.CancelFaceTraining
Halts face training that is currently in progress. A face training session stops automatically, so you do not need to use the misty.CancelFaceTraining()
command unless you want to abort a training that is in progress.
// Syntax
misty.CancelFaceTraining([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.CancelFaceTraining();
misty.ForgetAllFaces
Removes records of previously trained faces from Misty's memory.
// Syntax
misty.ForgetAllFaces([int prePauseMs], [int postPauseMs])
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.ForgetAllFaces();
misty.ForgetFace
Removes records of a specific trained face from Misty's memory.
// Syntax
misty.ForgetFace(string FaceId, [int prePauseMs], [int postPauseMs]);
Arguments
- FaceId (string) - The name of the face to remove.
// Example
misty.ForgetFace("John");
misty.GetKnownFaces
Obtains a list of the names of faces on which Misty has been successfully trained.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetKnownFaces([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetKnownFaces();
Returns
- Result (string) - A list of the names for faces that Misty has been trained to recognize. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
misty.StartFaceDetection
Initiates Misty's detection of faces in her line of vision. This command assigns each detected face a random ID.
When you are done having Misty detect faces, call misty.StopFaceDetection()
.
// Syntax
misty.StartFaceDetection([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartFaceDetection();
misty.StartFaceRecognition
Directs Misty to recognize a face she sees, if it is among those she has previously detected. To use this command, you must have previously used the misty.StartFaceDetection()
command to detect and store face IDs in Misty's memory.
When you are done having Misty recognize faces, call misty.StopFaceRecognition()
.
// Syntax
misty.StartFaceRecognition([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartFaceRecognition();
misty.StartFaceTraining
Starts Misty learning a face and assigns a name to that face.
This process should take less than 15 seconds and will automatically stop when complete. To halt an in-progress face training, you can call misty.CancelFaceTraining()
.
// Syntax
misty.StartFaceTraining(string faceId, [int prePauseMs], [int postPauseMs]);
Arguments
- faceId (string) - A unique string of 30 characters or less that provides a name for the face. Only alpha-numeric,
-
, and_
are valid characters. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartFaceTraining("My_Face");
misty.StartRecordingAudio
Starts Misty recording audio. Misty saves audio recordings to her local storage as .wav files. To stop recording, you must call the misty.StopRecordingAudio()
method.
// Syntax
misty.StartRecordingAudio(string filename, [int prePauseMs], [int postPauseMs]);
Warning: If you do not issue a misty.StopRecordingAudio()
command, Misty will continue recording until the audio file is 1 GB. Attempting to retrieve a file this large from Misty can cause the system to crash.
Note: Misty cannot record audio and listen for the "Hey, Misty!" key phrase at the same time. Recording audio automatically disables key phrase recognition.
Arguments
- fileName (string) - The name to assign to the audio recording. This parameter must include a
.wav
file type extension at the end of the string. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartRecordingAudio("RecordingExample.wav");
misty.StopFaceDetection
Stops Misty's detection of faces in her line of vision.
// Syntax
misty.StopFaceDetection([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StopFaceDetection();
misty.StopFaceRecognition
Stops the process of Misty recognizing a face she sees.
// Syntax
misty.StopFaceRecognition([int prePauseMs], [int postPauseMs])
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StopFaceRecognition();
misty.StopRecordingAudio
Directs Misty to stop the current audio recording and saves the recording to the robot under the fileName
name specified in the call to misty.StartRecordingAudio()
. Use this command after calling the misty.StartRecordingAudio()
command. If you do not call misty.StopRecordingAudio()
, Misty automatically stops recording after 60 seconds.
// Syntax
misty.StopRecordingAudio([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StopRecordingAudio();
misty.TakePicture
Takes a photo with Misty’s 4K camera.
Note: When you call the misty.TakePicture()
command immediately after using the camera to record a video, there may be a few seconds delay before Misty takes the photograph.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.TakePicture([string fileName], [int width], [int height], [bool displayOnScreen = false], [bool overwriteExisting = false], [string callback = _TakePicture()], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- fileName (string) - Optional. The filename to assign to the image file for the captured photo. Note that if you do not specify a filename, Misty does not save the photo to her local storage.
- width (integer) - Optional. A whole number greater than 0 specifying the desired image width (in pixels). Important: To reduce the size of a photo you must supply values for both
width
andheight
. Note that if you supply disproportionate values forwidth
andheight
, the system uses the proportionately smaller of the two values to resize the image. - height (integer) - Optional. A whole number greater than 0 specifying the desired image height (in pixels). Important: To reduce the size of a photo you must supply values for both
width
andheight
. Note that if you supply disproportionate values forwidth
andheight
, the system uses the proportionately smaller of the two values to resize the image. - displayOnScreen (boolean) - Optional. If
true
and afileName
is provided, displays the captured photo on Misty’s screen. Iffalse
or nofileName
value is provided, does nothing. Defaults tofalse
. - overwriteExisting (boolean) - Optional. Indicates whether Misty should overwrite an image with the same filename as the captured photo if one exists on her local storage. Passing in
true
overwrites a file with the same name. Passing infalse
prevents an existing file with the same name from being overwritten. In the case thatoverwriteExisting
is set tofalse
and a photo already exists with the same filename as the newly captured photo, the new photo is not saved to Misty. Defaults tofalse
. - callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
_TakePicture()
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.TakePicture("newImage", 1200, 1600, false, true);
Returns
- Result (object) - An object containing image data and meta information. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
- Base64 (string) - A string containing the Base64-encoded image data.
- ContentType (string) - The type and format of the image returned.
- Height (integer) - The height of the image in pixels.
- Name (string) - The name of the image.
- Width (integer) - The width of the image in pixels.
misty.StartRecordingVideo - BETA
Starts recording video with Misty's 4K Camera. Misty records videos in MP4 format at a resolution of 1080 × 1920 pixels.
Use misty.StopRecordingVideo()
to stop recording a video. Video recordings cannot be longer than 10 seconds. Misty stops recording automatically if a video reaches 10 seconds before you call misty.StopRecordingVideo()
.
Misty only saves the most recent video recording to her local storage. Recordings are saved with the filename MistyVideo.mp4
, and this file is overwritten with each new recording. To download a video from your robot, use the GetRecordedVideo
REST command.
Note: When you call the misty.StartRecordingVideo()
command immediately after using the RGB camera to take a picture, there may be a few seconds delay before Misty starts recording.
// Syntax
misty.StartRecordingVideo([int prePauseMs], [int postPauseMs])
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StartRecordingVideo();
misty.StartKeyPhraseRecognition - BETA
Starts Misty listening for the "Hey, Misty!" key phrase. When Misty hears the key phrase, the system sends a message to KeyPhraseRecognized
event listeners. Misty is only configured to recognize the "Hey, Misty" key phrase, and at this time you can't teach her to respond to other key phrases.
Note
- When you call the
misty.StartKeyPhraseRecognition()
command, Misty listens for the key phrase by continuously sampling audio from the environment and comparing that audio to her trained key phrase model (in this case, "Hey, Misty!"). Misty does not create or save audio recordings while listening for the key phrase. - To have Misty record what you say (for example, if you want to use speech to invoke other actions), you need to send a
misty.StartRecordingAudio()
command after receiving aKeyPhraseRecognized
event message. You can then do something with that audio file in your code, like hand it off to a third-party service for additional processing. - Misty cannot record audio and listen for the "Hey, Misty!" key phrase at the same time. Sending a command to start recording audio automatically stops key phrase recognition. To have Misty start listening for the key phrase after recording an audio file, you must issue another
misty.StartKeyPhraseRecognition()
command.
Follow these steps to code Misty to respond to the "Hey, Misty!" key phrase:
- Invoke the
misty.StartKeyPhraseRecognition()
command. - Register for
KeyPhraseRecognized
events. When Misty hears the key phrase, she sends a message toKeyPhraseRecognized
event listeners. - Write the code to handle what Misty should do when she hears the key phrase inside the
KeyPhrasedRecognized
event callback. For example, you might have Misty turn to face you or start recording audio to hand off to a third-party service for additional processing.
Note: When Misty recognizes the key phrase, she automatically stops listening for key phrase events. In order to start Misty listening for the key phrase again, you need to issue another misty.StartKeyPhraseRecognition()
command.
// Syntax
misty.StartKeyPhraseRecognition([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
As an example of how to use this functionality in your skill code, the following has Misty play a sound and wave when she hears the key phrase.
StartKeyPhraseRecognition();
function StartKeyPhraseRecognition() {
misty.Debug("Starting key phrase recognition...");
// Starts Misty listening for the "Hey, Misty" key phrase
misty.StartKeyPhraseRecognition();
// Registers for KeyPhraseRecognized events
misty.RegisterEvent("KeyPhraseRecognized","KeyPhraseRecognized", 10, false);
misty.Debug("KeyPhraseRecognition started. Misty will play a sound and wave when she hears 'Hey Misty'.");
}
// Callback function to execute when Misty hears the key phrase
function _KeyPhraseRecognized() {
waveRightArm();
misty.Debug("Key phrase recognized!");
misty.Debug("Audio recording stopped. Starting key phrase recognition again...");
// Starts Misty listening for the key phrase again
StartKeyPhraseRecognition();
}
// Helper function to wave Misty's arm
function waveRightArm() {
misty.MoveArmDegrees("left", 90, 45); // Left arm fully down
misty.Pause(50);
misty.MoveArmDegrees("right", 90, 45); // Right arm fully down
misty.Pause(50); // Pause for 3 seconds
misty.MoveArmDegrees("right", -45, 45); // Right arm fully up
misty.Pause(7000); // Pause with arm up for 5 seconds (wave!)
misty.MoveArmDegrees("right", 90, 45); // Right arm fully down
}
misty.StopKeyPhraseRecognition - BETA
Stops Misty listening for the "Hey, Misty!" key phrase.
// Syntax
misty.StopKeyPhraseRecognition([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
misty.StopRecordingVideo - BETA
Stops recording video with Misty's 4K camera.
Use this command after calling misty.StartRecordingVideo()
. Video recordings cannot be longer than 10 seconds. Misty stops recording automatically if a video reaches 10 seconds before you call this command. To download a video from your robot, use the GetRecordedVideo
REST command.
// Syntax
misty.StopRecordingVideo([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.StopRecordingVideo();
Skill Management
misty.CancelSkill
Cancel execution a specified skill.
// Syntax
misty.CancelSkill(string skill, [int prePauseMs], [int postPauseMs])
Arguments
- Skill (string) - The skill's unique GUID identification string. Use the value of the
UniqueId
parameter from the skill's JSON meta file. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.CancelSkill("c3f9b33b-d895-48cf-8f15-cdcf5a866bde");
misty.GetRunningSkills
Obtains a list of the skills currently running on Misty.
Note: With local skills, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
//Syntax
misty.GetRunningSkills([string callback], [string callbackRule], [string skillToCall], [int prePauseMs], [int PostPause])
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
_GetRunningSkills()
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
//Example
misty.GetRunningSkills();
Returns
- result (array) - A list of objects with meta information about the skills currently running on Misty. If no skills are currently running, this command returns an empty array. Note that in a local skill, data returned by this command must be passed into a callback function to be processed and made available for use in your skill (see "Get" Data Callbacks for more information). Each object in the list includes the following key-value pairs:
- description (string) - The description of the skill as it appears in the skill's meta file.
- name (string) - the name of the skill, as it appears in the skill's meta file.
- startupArguments (object) - An object with key-value pairs for each startup argument in the skill's meta file.
- uniqueId (string) - The unique id of the skill, from the skill's meta file.
misty.RunSkill
Immediately runs a previously uploaded skill.
// Syntax
misty.RunSkill(string skill, [string method], [int prePauseMs], [int postPauseMs])
Arguments
- skill (string) - The skill's unique GUID identification string. Use the value of the
UniqueId
parameter from the skill's JSON meta file. - method (string) - Optional. A specific method within a skill to run, which can be useful for testing. If no value is specified for the
method
parameter,RunSkill
by default starts running the skill from the beginning. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.RunSkill("bb20ff02-edac-475c-af0c-a06e81e5dc50");
misty.Debug - ALPHA
Publishes a string to subscribers of the SkillData
named object. Use this method to print debug messages to the console in your web browser when you use Skill Runner.
You can think of misty.Debug()
as the Misty version of console.log()
. When you use Skill Runner to run a skill, the web page subscribes to the SkillData
named object via Misty's WebSocket connection. This allows Misty to print error messages, debug messages, and other skill data to the console in your web browser. Use misty.Debug()
to print your own messages to the console.
Note: Data you pass into the misty.Debug()
message must be a string. To send a data object, you can serialize your data into a string and parse it out on the client side of the SkillData
subscription. If BroadcastMode
is set to off
in the meta file for a skill, the skill does not publish debug data.
// Syntax
misty.Debug(string data, [int prePauseMs], [int postPauseMs]);
Arguments
- data (string) - The debug message to publish.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.Debug("Message")
misty.Get - ALPHA
Returns data saved to the robot using misty.Set()
.
// Syntax
misty.Get(string key, [int prePauseMs], [int postPauseMs]);
Arguments
- key (string) - The key name of the data to return.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.Get("Key");
Returns
- value (string, boolean, integer, or double) - The data associated with the specified key.
misty.Keys - ALPHA
Returns a list of all the available persistent data stored on the robot.
// Syntax
misty.Keys([int prePauseMs], [int postPauseMs]);
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.Keys();
Returns
- keys (list) - A list of the keys and values for all available persistent data stored on the robot.
misty.Pause - ALPHA
Pause skill execution for a specified number of milliseconds.
// Syntax
misty.Pause(int prePauseMs)
Arguments
- prePauseMs (integer) - The duration in milliseconds to pause skill execution.
// Example
misty.Pause(1000);
misty.Publish - ALPHA
Writes data to the robot's internal log.
Note that misty.Publish()
writes data to the robot's internal log file, even when called in a skill with the value of WriteToLog
set to False
in its meta file. You can use the Command Center to download your robot's log files, or send a GET request to the REST endpoint for the GetLogFile
command.
// Syntax
misty.Publish(string name, string data)
Arguments
- name (string) - A name for the data to write to the robot's log.
- data (string, integer, double, or boolean) - The data to write to the robot's log. To write an object, you must serialize your data into a string using
JSON.stringify()
.ƒ
// Example
misty.Publish("data-name", "data-value");
misty.RandomPause - ALPHA
Pause skill execution for a random duration.
// Syntax
misty.RandomPause(int minimumDelay, int maximumDelay)
Arguments
- minimumDelay (integer) - The minimum duration in milliseconds to pause skill execution.
- maximumDelay (integer) - The maximum duration in milliseconds to pause skill execution.
// Example
misty.RandomPause(1000, 2000);
misty.Remove - ALPHA
Removes data that has been saved to the robot under a specific key with misty.Set()
.
// Syntax
misty.Remove(string key, [int prePauseMs], [int postPauseMs])
Arguments
- key (string) - The key name of the data to remove.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.Remove("Key");
misty.Set - ALPHA
Saves data that can be validly updated and used across threads or shared between skills.
Data saved using misty.Set()
must be one of these types: string
, bool
, int
, or double
. Alternately, you can serialize your data into a string using JSON.stringify()
and parse it out again using JSON.parse()
.
By default, long term data saved by the misty.Set()
command clears from Misty's memory when Misty reboots. To change this, you need to include an additional SkillStorageLifetime
key in the meta file for your skill. The SkillStorageLifetime
key determines how long data saved to Misty with the misty.Set()
command remains available for use in your skills. You can set the value of SkillStorageLifetime
to Skill
, Reboot
, or LongTerm
.
Skill
- The data clears when the skill stops running.Reboot
- The data clears the next time Misty reboots.LongTerm
- The data persists across reboots and remains available until removed from the robot with the misty.Remove()
command.
You can safely omit the SkillStorageLifetime
key from the meta file if you do not want to modify the default behavior of persistent data for that skill.
// Syntax
misty.Set(string key, string value, [bool longTermStorage], [int prePauseMs], [int postPauseMs]);
Arguments
- key (string) - The key name for the data to save.
- value (value) - The data to save. Data saved using
misty.Set()
must be one of these types:string
,bool
,int
, ordouble
. - longTermStorage (boolean) - Whether to save the data to long term storage. Defaults to
false
. - prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next comm
and in the skill. If no command follows this command,
postPauseMs
is not used.
System
misty.ClearDisplayText
Force-clears an error message from Misty’s display. Note: This command is provided as a convenience. You should not typically need to call misty.ClearDisplayText()
.
// Syntax
misty.ClearDisplayText ([int prePauseMs], [int postPauseMs])
Arguments
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.ClearDisplayText();
misty.ConnectToSavedWifi
Connects Misty to a saved Wi-Fi network.
// Syntax
misty.ConnectToSavedWifi(string networkId, [int prePauseMs], [int postPauseMs])
Arguments
- networkId (string) - The name of the network to connect to.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.ConnectToSavedWifi("MyHomeWifi")
misty.ForgetWifi
Deletes information about a Wi-Fi network from Misty’s list of saved networks. If you call this method without any arguments, Misty deletes information for all of her saved networks.
// Syntax
misty.ForgetWifi(string networkId, [int prePauseMs], [int postPauseMs])
Arguments
- networkId (string) - Optional. The network to remove from Misty’s list of saved networks. If you call this method without any arguments, Misty deletes information for all of her saved networks.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.ForgetWifi("MyHomeWifi")
misty.GetAvailableWifiNetworks
Obtains a list of local WiFi networks and basic information regarding each.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetAvailableWifiNetworks([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetAvailableWifiNetworks();
Returns
- Result (array) - An array containing one element for each WiFi network discovered. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information. Each element contains the following:
- Name (string) - The name of the WiFi network.
- SignalStrength (integer) - A numeric value for the strength of the network.
- IsSecure (boolean) - Returns
true
if the network is secure. Otherwise,false
.
misty.GetBatteryLevel
Obtains Misty's current battery level, along with other information about the battery.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetBatteryLevel([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetBatteryLevel();
Returns
- Result (object) - An object with information about Misty's battery. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information. Includes the following properties:
- chargePercent (double)
- created (string)
- current (int)
- expiry (string)
- healthPercent (double)
- isCharging (bool)
- sensorId (string)
- sensorName (string)
- state (string)
- temperature (int)
- trained (bool)
- voltage (double)
misty.GetDeviceInformation
Obtains device-related information for the robot.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetDeviceInformation([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetDeviceInformation();
Returns
- Result (object) - An object containing information about the robot, with the following fields. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
- batteryLevel - The battery charge percentage (in decimal format) and the current battery voltage.
- currentProfileName - The name of the network that the robot is on.
- hardwareInfo - Hardware and firmware version information for both the Real Time Controller board and the Motor Controller board.
- ipAddress - The IP address of the robot.
- networkConnectivity - The status of the robot's network connection. Possible values are Unknown, None, LocalAccess, LimitedInternetAccess, InternetAccess.
- occipitalDeviceInfo - An object with driver, firmware, and serial information for the robot's Occipital Structure Core depth sensor.
- outputCapabilities - An array listing the output capabilities for this robot.
- robotId - The robot's unique ID, if set. Default value is all zeros.
- robotVersion - The version number for the HomeRobot app running on the robot.
- sensorCapabilities - An array listing the sensor capabilities for this robot.
- sensoryServiceAppVersion - The version number for the Sensory Service app running on the robot.
- serialNumber - The unique serial number for the robot.
- windowsOSVersion - The version of Windows IoT Core running on the robot.
misty.GetHelp
Obtains information about a specified API command. Calling misty.GetHelp()
with no parameters returns a list of all the API commands that are available.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetHelp([string endpointName], [string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- endpointName (string) - Optional. A command in
"Api.<COMMAND>"
format eg:"Api.GetAudioList"
. If no command name is specified, callingmisty.GetHelp()
returns a list of all API commands. - callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
<_CommandName>
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetHelp();
Returns
- Result (string) - A string containing the requested help information. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
misty.GetLogFile
Obtains log file data.
The response object includes data from the current day (or the specified date, if one exists). It includes up to 3MB of data from log files up to 14 days old. Due to the 3MB limit, log data from the oldest date returned is typically truncated. Misty automatically deletes log files older than 14 days.
Note: Misty returns the messages for each day in order from the earliest message logged to the latest message logged on that day. In the response object, the time jump from one day to the next is not demarcated in any way.
With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _GetLogFile()
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetLogFile([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, results are passed into the default
_GetLogFile()
callback function. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetLogFile();
// Callback function to handle result
function _GetLogFile(data) {
misty.Debug(JSON.stringify(data.Result));
};
Returns
- Result (string) - Compiled log file data. Returns an error message if no log data is found. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
misty.GetLogLevel
Obtains Misty's current log level.
// Syntax
misty.GetLogLevel([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Misty's log level determines where the system writes different types of messages. Misty can write messages to her local log file and to a remote log file on a server owned by Misty Robotics.
If Misty's log level is set to Debug
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | ✓ |
Warn | ✓ | ✓ |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
If Misty's log level is set to Info
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | ✓ |
Warn | ✓ | ✓ |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
If Misty's log level is set to Warn
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | |
Warn | ✓ | ✓ |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
If Misty's log level is set to Error
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | |
Warn | ✓ | |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
Arguments
- callback (string) - Optional. The name of the callback function to call when the data returned by this command is ready. If empty, the default callback function (
_GetLogLevel()
) is called. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetLogLevel();
Returns
- level (string) - The current log level of the robot. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
misty.GetSavedWifiNetworks
Obtains Misty's list of saved network IDs.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetSavedWifiNetworks([string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Arguments
- callback (string) - Optional. The name of the callback function to execute on data returned by this command. If empty, the default
_GetSavedWifiNetworks()
function executes on callback data. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetSavedWifiNetworks();
// When data is ready, send it to debug listeners
function _GetSavedWifiNetworks(data) {
misty.Debug(JSON.stringify(data));
};
Returns
- Result - An array of objects with data about Misty's saved Wi-Fi networks. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information.
Example JSON object for a saved WiFi network:
{
"bssid": null,
"detailedState": null,
"frequency": 0,
"hidden": false,
"ipAddress": null,
"linkSpeed": 0,
"networkId": 0,
"physicalAddress": null,
"ssid": "\"NetworkID\"",
"status": "Unknown",
"supplicantState": null
}
misty.GetWebsocketNames
Obtains information about a specified WebSocket class. Calling misty.GetWebsocketNames()
without specifying a class returns information about all of Misty’s available WebSocket connections.
Note: For more detailed information about each of Misty’s WebSocket connections, see Event Types.
Note: With the on-robot JavaScript API, data returned by this and other "Get" type commands must be passed into a callback function to be processed and made available for use in your skill. By default, callback functions for "Get" type commands are given the same name as the correlated command, prefixed with an underscore: _<COMMAND>
. For more on handling data returned by "Get" type commands, see "Get" Data Callbacks.
// Syntax
misty.GetSavedWifiNetworks([string websocketClass], [string callback], [string callbackRule = "synchronous"], [string skillToCall], [int prePauseMs], [int postPauseMs]);
Parameters
- websocketClass (string) - Optional. Specifies the WebSocket class to obtain information about. To recieve information about all of Misty's available WebSocket connections, pass an empty string.
- callback (string) - Optional. The name of the callback function to execute on data returned by this command. If empty, the default
_GetWebsocketNames()
function executes on callback data. - callbackRule (string) - Optional. The callback rule for this command. Available callback rules are
"synchronous"
,"override"
, and"abort"
. Defaults to"synchronous"
. For a description of callback rules, see "Get" Data Callbacks. - skillToCall (string) - Optional. The unique id of a skill to trigger for the callback, instead of calling back into the same skill.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.GetWebsocketNames("");
// When data is ready, send it to debug listeners
function _GetWebsocketNames(data) {
misty.Debug(JSON.stringify(data));
};
Returns
- result (array) - An array of data objects with information about the WebSocket connections to which you can subscribe. With Misty's on-robot JavaScript API, data returned by this command must be passed into a callback function to be processed and made available for use in your skill. See "Get" Data Callbacks for more information. The data object for each WebSocket class includes the following information:
- class (string) - The name of a given WebSocket class.
- nestedProperties (array) - A list of properties for a given WebSocket class. Use these properties to declare conditions for events you want to receive information about when subscribing to messages from a WebSocket data stream.
misty.SetDefaultVolume
Sets the default loudness of Misty's speakers for audio playback.
// Syntax
misty.SetDefaultVolume(int volume, [int prePauseMs], [int postPauseMs]);
Arguments
- volume (integer): A value between 0 and 100 for the loudness of the system audio. 0 is silent, and 100 is full volume. By default, the system volume is set to 100.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.SetDefaultVolume(100);
misty.SetLogLevel
Sets Misty's log level. Misty's log level can be set to Debug
, Info
, Warn
, or Error
.
// Syntax
misty.SetLogLevel(string level, [int prePauseMs], [int postPauseMs]);
Misty's log level determines where the system writes different types of messages. Misty can write messages to her local log file and to a remote log file on a server owned by Misty Robotics. See the tables below for information about how Misty's log level determines where different message types are published.
If Misty's log level is set to Debug
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | ✓ |
Warn | ✓ | ✓ |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
If Misty's log level is set to Info
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | ✓ |
Warn | ✓ | ✓ |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
If Misty's log level is set to Warn
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | |
Warn | ✓ | ✓ |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
If Misty's log level is set to Error
:
Message Type: | Logged Locally | Logged Remotely |
---|---|---|
Debug | ✓ | |
Info | ✓ | |
Warn | ✓ | |
Error | ✓ | ✓ |
Remote | ✓ | ✓ |
Arguments
- level (string) - The level to set the log to. Accepts
Debug
,Info
,Warn
, orError
. - prePause (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.SetLogLevel("Debug");
misty.SetNetworkConnection
Connects Misty to a specified Wi-Fi source.
// Syntax
misty.SetNetworkConnection(string networkName, string password, [int prePauseMs], [int postPauseMs])
Arguments
- networkName (string) - The Wi-Fi network name (SSID).
- password (string) - The Wi-Fi network password.
- prePauseMs (integer) - Optional. The length of time in milliseconds to wait before executing this command.
- postPauseMs (integer) - Optional. The length of time in milliseconds to wait between executing this command and executing the next command in the skill. If no command follows this command,
postPauseMs
is not used.
// Example
misty.SetNetworkConnection("myWiFiNetwork", "myWiFiPassword")
misty.ConvertIntentToCommand - ALPHA
Translates a given string and set of arguments to invoke a command from Misty's API.
// Syntax
misty.ConvertIntentToCommand(string command, [string argument]...);
Note: As an alpha feature, the misty.ConvertIntentToCommand()
method is in active development, and it may not always produce the expected result. You can expect this method to be modified and improved with future updates to Misty's software.
Arguments:
- command (string) - A string that matches the internal name of a command from Misty's API. Note: The
misty.ConvertIntentToCommand()
method currently expects the value passed in for the thecommand
argument to match an internal name that Misty uses to recognize and execute the command. Sometimes these internal command names differ from the method names used in Misty's JavaScript API. For example, calling themisty.DisplayImage()
method in Misty's JavaScript API invokes the the command known internally asChangeDisplayImage
. You can find the internal names of Misty's commands by issuing a GET request to theGetHelp
endpoint (<robot-ip-address>/api/help
) and checking the values for theid
keys in the response object. - argument - (string) - One or more unique strings that hold the value for arguments to pass into the given
command
.
When passing in values for more than one argument, you must pass in the value for each argument as a unique string. As an example, the following invokes Misty's ChangeLED
command with unique values for the red
, green
, and blue
arguments to change Misty's chest LED color.
// Invokes the ChangeLED command
misty.ConvertIntentToCommand("ChangeLED", "0", "255", "0");
Tip: The misty.ConvertIntentToCommand()
method simplifies the task of coding Misty to respond when you issue a voice command to invoke a command from her API. When you use Misty's StartKeyPhraseRecognition
command and register for KeyPhraseRecognized
events, you can code Misty to start recording audio inside the KeyPhraseRecognized
callback. You can then send this recorded audio off for processing by a third party service like Dialogflow that's configured to identify the intent of a speaker from a given speech recording. Pass this intent (and any additional arguments that you parse out in your skill code) into your misty.ConvertIntentToCommand()
method to have Misty execute the matching command.