mistycommunity / documentation

The repository for the Misty Robotics developer documentation.

Misty Robotics Developer Documentation

This repo contains the source files for the Misty Robotics developer documentation. If you want to read the docs, head over to https://docs.mistyrobotics.com/.

Contributing to Misty's Documentation

This documentation is early stage and is growing continuously. We're grateful for all feedback and contributions.

Found something small that you think should be changed?

Create an issue right here in the repo!

Want to contribute something bigger than a bug report?

First, before you invest too much time, reach out and let us know what you're thinking. It may be that we already know about the issue or are already creating new content. Reaching out could save you time and effort.

Second, assuming we're not already making the changes, go ahead and fork the repo. After editing the source files, build the documentation locally and make a pull request, as described here.

---

The Misty Robotics documentation is based on a design by Particle, is built with Metalsmith, and is formatted using Markdown.

documentation's Issues

npm install doesn't work.

when running npm install on the root directory I run into issues.

npm ERR! Cannot read property '0' of undefined
npm ERR! A complete log of this run can be found in:

documentation get started I found a difference for console Control - Shift - I for me

This is just in case it helps if you want to add others, or just be aware of the difference.

https://docs.mistyrobotics.com/misty-ii/robot/get-started/
https://github.com/MistyCommunity/Documentation/blob/facetraining/src/content/misty-ii/robot/get-started.md

Current statement:
Open your browser's web console to view debug messages, error messages, and other data Misty sends to the Skill Runner web page. To open the web console in Chrome, use Ctrl + Shift + J (Windows) Ctrl + Shift + X (Linux) Cmd + Option + J (Mac).

** For my flavor you can either use the verticle '...' -> More Tools -> Developer Tools
or Control -Shift - I to open the console.

It may be different on other flavors of linux or Chrome
I am running Fedora release 29 (Twenty Nine) And Chrome 75.0.3770.142

bash-4.4$ uname -a
Linux localhost.localdomain 5.1.18-200.fc29.x86_64 #1 SMP Mon Jul 15 16:09:08 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux

Google Chrome	75.0.3770.142 (Official Build) (64-bit)
Revision	8d93477bd18154c67a70a67019cb8032382c55dd-refs/branch-heads/3770@{#1160}
OS	Linux
JavaScript	V8 7.5.288.30
Flash	32.0.0.207 /home/mwd/.config/google-chrome/PepperFlash/32.0.0.207/libpepflashplayer.so
User Agent	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36

Provide information about first message sent after WebSocket subscription

The first message that Misty sends when you subscribe to a WebSocket from a remote device contains meta information about that WebSocket connection. It does not contain any information related to the sensor/data event that the subscription is for. This causes confusion; developers may assume this first message contains event-specific data and write code that doesn't work.

We should add a note to this page describing the nature of this first message and how to use it or ignore it as needed.

Missing header definitions in REST API reference documentation

The REST API reference documentation should include a definition of all headers returned by requests to Misty.

Defect in trigger event docs

https://github.com/MistyCommunity/Documentation/blob/master/src/content/misty-ii/javascript-sdk/javascript-skill-architecture.md states:

To trigger user events from a skill, you must invoke the TriggerSkill command. You must also register event listeners in any skills you want to receive the event.

This is false. There is no TriggerSkill command in the JS/.NET SDK. This should be "TriggerEvent" command.

broken URL in README

Summary

in the README, docs.mistyrobotics.com is automatically treated as a URL, but the result is broken.

Proposed solution

write the full URL, e.g., https://docs.mistyrobotics.com/

Missing public beta command - GetWebSocketHelp

Need to add to "information" section of API docs. Per conversation w/ Donna:

"[this] is the other WebsocketHelp call we created to help folks know what data is in each websocket data packet... The name needs to be the same as the Base API command, not the class name they called it"

This is the endpoint:
http://{robo-ip}/api/beta/info/help/websocket

External Requests tutorial is not up-to-date

The External Requests tutorial under Using Local Skills is not up to date with the current version of Misty's software. The most recent release includes new parameters for the misty.SendExternalRequest() command that are not yet included in the tutorial.

Call out response data for Facial Detection events

I just learned there is a 'distance' field that is a part of the reponse from a successful facial detection event that is the estimated distance in meters from the robot that the face was seen.

This is based on an average face size and is a loose approximation of distance. We should call out all the available response data that comes back from the robot.

Would love more detail on logging system

The current SetLogLevel documentation is good in the sense that it oulines the various log levels. What is missing, which is especially important to those with heightened interest over information flow and information security, is more detail on the exact types of data that are communicated from the robot to the Misty cloud servers for each level (e.g. API -- all? all data within the API or just the API call itself? Error - just the error number? or other content about the error? All APIs or a subset? All errors or a subset?

It would be great to augment with more specifics about the data that's actually conveyed. Maybe even with an example with highlighted data that illustrates the various classes of data.

Duplicating hyperlinks in src files breaks sidebar navigation

Encountered an issue in a recent build where sidebar nav links were broken on the Docs Home page (al links in the sidebar redirected to the Docs Home page). This happened when I added a second link to the Misty Community forums to src/content/index.md. Removing this second link fixed the sidebar nav.

Feedback on Hello World Tutorial

For file https://github.com/MistyCommunity/Documentation/blob/master/src/content/misty-ii/robot/hello-world.md

At https://docs.mistyrobotics.com/misty-ii/robot/hello-world/#changing-misty-39-s-led, the docs say (a few times):

Use the Skill Runner to upload your modified HelloWorld.js file to Misty.

and underneath the first time, the note below it says:

If you did not change the name of the JavaScript code file for your Hello World skill, then there's no need to upload a new JSON meta file to Misty.

However, if I try to upload just the .js file, the Skill Runner page returns an error

Skill file uploads must include a json meta file.

(FYI, I do seem to be able to upload the json file without the JavaScript code file.)

Lines 296 and 339 say:

        Math.floor(i * blue)); // red intensity

The comment should say 'blue' intensity, not 'red'.

Lines 628 and 662 say:

If misty sees someone she doesn't know, she raises her eyebrow

The word 'Misty' should be capitalized to match other references to Misty in comment lines.

URL Typo in system-updates.md

https://github.com/MistyCommunity/Documentation/blob/master/src/content/misty-ii/robot/system-updates.md

Has:
You can check the software versions on your Misty by sending a request to the endpoint for the [GetDeviceInformation](../../..//misty-ii/reference/rest/#getdeviceinformation) command. Look for the values of the following properties in the JSON object that Misty returns:

It should be:

You can check the software versions on your Misty by sending a request to the endpoint for the [GetDeviceInformation](../../../misty-ii/reference/rest/#getdeviceinformation) command. Look for the values of the following properties in the JSON object that Misty returns:

The extra slash sends people to a page not found at https://docs.mistyrobotics.com/misty-ii/robot/system-updates/

SaveAudio docs should have information about supported codecs & formats.

This information will help developers understand how to use audio assets effectively in their skills.

MistyVoice needs some attention

The 'Misty Voice' link referenced is in need of some updating (Currently does not work)

https://github.com/MistyCommunity/MistyI/tree/master/API_Wrappers/Python/samples/mistyvoice

another broken URL in README

Summary

in the README, docs.particle.io is automatically treated as a URL, but the result is broken.

Proposed solution

write the full URL, e.g., https://docs.particle.io/

Related issuse

#23
(next time I will be more careful to collect these all into a single issue.)

GetSlamStatus docs are incomplete

The example response data given for the GetSlamStatus command appears to be out of date. The existing parameters and values require more thorough definition to be useful.

halt command?

Should it be POST /api/halt, not POST /api/robot/halt that is written at https://github.com/MistyCommunity/Documentation/blob/15e5b5fc86450fb13f0b32542f2822b840e2bec1/src/content/docs/reference/rest.md#halt (and as released at https://docs.mistyrobotics.com/docs/reference/rest/#halt)?

I have an FEP robot, and the response to POST /api/robot/halt is

{"error":"'/robot/halt' command not found for post request","status":"Failed"}

whereas POST /api/halt succeeds.

Plugins for AWS deployment from command line?

I'd like to be able to deploy to AWS from the command line. Posting an issue for this as a reminder to do further research.

The author of this article used Bucketful. Looks promising.

404 on http://commity.mistryrobotics.com

Hi, I just got my misty robot and was looking for the support web page and community.

The link to http://commity.mistryrobotics.com used in the Misty app and on https://github.com/MistyCommunity gives a 404 error.

I guess this is the support forum is now on slack? If so, it would be great to just forward http://commity.mistryrobotics.com to the slack channel and add some information on how to work with the forum, where to ask questions and raise issues.

Best, Jens

Tooling doesn't work on Windows

Doing npm start on a Windows machine returns an error like this:

> node ./scripts/server.js

[metalsmith-watch] ✓ Live reload server started on port: 35729
TypeError: Cannot read property 'split' of undefined
    at createInPageIndexes (C:\Path\Documentation\node_modules\metalsmith-lunr\lib\index.js:66:49)
    at indexDocs (C:\Path\Documentation\node_modules\metalsmith-lunr\lib\index.js:43:27)
    at Ware.<anonymous> (C:\Path\Documentation\node_modules\metalsmith-lunr\lib\index.js:11:5)
    at Ware.<anonymous> (C:\Path\Documentation\node_modules\metalsmith\node_modules\wrap-fn\index.js:45:19)
    at next (C:\Path\Documentation\node_modules\metalsmith\node_modules\ware\lib\index.js:85:20)
    at C:\Path\Documentation\node_modules\metalsmith\node_modules\wrap-fn\index.js:121:18
    at C:\Path\mistydoc\Documentation\node_modules\metalsmith-autotoc\index.js:142:7
    at done (C:Path\Documentation\node_modules\metalsmith-autotoc\node_modules\async\lib\async.js:132:19)
    at C:\Path\Documentation\node_modules\metalsmith-autotoc\node_modules\async\lib\async.js:32:16
    at C:\Path\Documentation\node_modules\metalsmith-autotoc\index.js:139:9
    at C:\Path\Documentation\node_modules\metalsmith-autotoc\node_modules\async\lib\async.js:122:13
    at _each (C:\Path\Documentation\node_modules\metalsmith-autotoc\node_modules\async\lib\async.js:46:13)
    at Object.async.each (C:\Path\Documentation\node_modules\metalsmith-autotoc\node_modules\async\lib\async.js:121:9)
    at Ware.<anonymous> (C:\Path\Documentation\node_modules\metalsmith-autotoc\index.js:116:11)
    at Ware.<anonymous> (C:\Path\Documentation\node_modules\metalsmith\node_modules\wrap-fn\index.js:45:19)
    at Immediate.next (C:\Path\Documentation\node_modules\metalsmith\node_modules\ware\lib\index.js:85:20)
    at Immediate._onImmediate (C:\Path\Documentation\node_modules\metalsmith\node_modules\wrap-fn\index.js:121:18)
    at runCallback (timers.js:794:20)
    at tryOnImmediate (timers.js:752:5)
    at processImmediate [as _immediateCallback] (timers.js:729:5) 'TypeError: Cannot read property \'split\' of undefined\n    at createInPageIndexes (C:\\Path\\Documentation\\node_modules\\metalsmith-lunr\\lib\\index.js:66:49)\n    at indexDocs (C:\\Path\\Documentation\\node_modules\\metalsmith-lunr\\lib\\index.js:43:27)\n    at Ware.<anonymous> (C:\\Path\\Documentation\\node_modules\\metalsmith-lunr\\lib\\index.js:11:5)\n    at Ware.<anonymous> (C:\\Path\\Documentation\\node_modules\\metalsmith\\node_modules\\wrap-fn\\index.js:45:19)\n    at next (C:\\Path\\Documentation\\node_modules\\metalsmith\\node_modules\\ware\\lib\\index.js:85:20)\n    at C:\\Path\\Documentation\\node_modules\\metalsmith\\node_modules\\wrap-fn\\index.js:121:18\n    at C:\\Path\\Documentation\\node_modules\\metalsmith-autotoc\\index.js:142:7\n    at done (C:\\Path\\Documentation\\node_modules\\metalsmith-autotoc\\node_modules\\async\\lib\\async.js:132:19)\n    at C:\\Path\\Documentation\\node_modules\\metalsmith-autotoc\\node_modules\\async\\lib\\async.js:32:16\n    at C:\\Path\\Documentation\\node_modules\\metalsmith-autotoc\\index.js:139:9\n    at C:\\Path\\Documentation\\node_modules\\metalsmith-autotoc\\node_modules\\async\\lib\\async.js:122:13\n    at _each (C:\\Path\\Documentation\\node_modules\\metalsmith-autotoc\\node_modules\\async\\lib\\async.js:46:13)\n    at Object.async.each (C:\\Path\Documentation\\node_modules\\metalsmith-autotoc\\node_modules\\async\\lib\\async.js:121:9)\n    at Ware.<anonymous> (C:\\Path\\Documentation\\node_modules\\metalsmith-autotoc\\index.js:116:11)\n    at Ware.<anonymous> (C:\\Path\\Documentation\\node_modules\\metalsmith\\node_modules\\wrap-fn\\index.js:45:19)\n    at Immediate.next (C:\\Path\\Documentation\\node_modules\\metalsmith\\node_modules\\ware\\lib\\index.js:85:20)\n    at Immediate._onImmediate (C:\\Path\\Documentation\\node_modules\\metalsmith\\node_modules\\wrap-fn\\index.js:121:18)\n    at runCallback (timers.js:794:20)\n    at tryOnImmediate (timers.js:752:5)\n    at processImmediate [as _immediateCallback] (timers.js:729:5)'

I found a related issue in the Particle docs repo (the Misty docs are based on their toolchain): particle-iot/docs#384

This comment is from one of the Particle engineers:

Sorry to say this isn't likely to be a simple fix. I don't think the Metalsmith static site generator and all the plugins we use are well tested on Windows."

The issue appears to be related to the metalsmith-lunr and/or lunr.js dependencies. If I remove references to these libraries from the metalsmith.js build script, then npm start works, and the site builds...but, it builds incorrectly, because we actually use those dependencies to build out the search functionality. Removing them screws up the build process and breaks search and other parts of the site.

Unfortunately, removing these dependencies is not a guaranteed fix. It appears that the Particle + Metalsmith toolchain isn't comprehensively tested on Windows to begin with, and there may be other problems that come up once this issue is resolved.

npm start doesn't always work the first time

The first time you do npm start to build a local version of the docs site, you may get an error that looks like this:

> node ./scripts/server.js

module.js:549
    throw err;
    ^

Error: Cannot find module 'metalsmith-redirect'
    at Function.Module._resolveFilename (module.js:547:15)
    at Function.Module._load (module.js:474:25)
    at Module.require (module.js:596:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (C:\Users\Johnathan\Desktop\mistydoc\Documentation\scripts\redirects.js:2:16)
    at Module._compile (module.js:652:30)
    at Object.Module._extensions..js (module.js:663:10)
    at Module.load (module.js:565:32)
    at tryModuleLoad (module.js:505:12)
    at Function.Module._load (module.js:497:3)
    at Module.require (module.js:596:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (C:\Path\Documentation\scripts\metalsmith.js:28:17)
    at Module._compile (module.js:652:30)
    at Object.Module._extensions..js (module.js:663:10)
    at Module.load (module.js:565:32)
    at tryModuleLoad (module.js:505:12)
    at Function.Module._load (module.js:497:3)
    at Module.require (module.js:596:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (C:\Path\Documentation\scripts\server.js:1:76)
    at Module._compile (module.js:652:30)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] start: `node ./scripts/server.js`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] start script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Path\npm-cache\_logs\2020-05-12T15_29_17_088Z-debug.log

To workaround the issue:

1. Delete the node_modules directory
2. Redo npm install
3. Retry npm start

The site should build and you should see it at localhost:8080

broken link

To reproduce

1. go to https://docs.mistyrobotics.com/misty-ii/reference/javascript-api/
2. try to follow link to "JavaScript SDK Architecture" in the left navigation bar

Proposed solution

the link is currently https://docs.mistyrobotics.com/misty-ii/coding-misty/javascript-sdk-architecture, but it should be https://docs.mistyrobotics.com/misty-ii/javascript-sdk/javascript-skill-architecture/

APIXU no longer exists

APIXU was shut down as of 10/14/2019 and updated to weatherstack. APIXU is currently referenced as part of the external request example: https://docs.mistyrobotics.com/misty-ii/coding-misty/javascript-sdk-tutorials/#external-requests

General feedback for Misty II App and Overview pages

For file https://github.com/MistyCommunity/Documentation/blob/master/src/content/tools-%26-apps/mobile/misty-app.md

Just letting you know the screen shots don't seem to match the current app version (e.g., The home screen shot at https://docs.mistyrobotics.com/tools-&-apps/mobile/misty-app/#getting-information-about-misty has a grid of buttons with WiFi info, forums, etc which don't show up on the iOS app as of writing this (9/7/19).

I'm in a hotel, and connecting to a password protected wifi network (not an open network, no captive portals) and when I connect Misty II to the network I am getting a dialog box that says

Wifi Network Mismatch
Your phone and Misty are currently on different wifi networks. Some app functions won't be available. Would you like to change Misty's wifi network?

I tried to change it a few times but keep getting the same dialog box, When I gave up and said 'no'. the IP address allocated to Misty II was on the same /24 subnet:

My phone:
IP: 10.43.0.200
Subnet: 255.255.255.0
Router: 10.43.0.1

Misty II:
IP 10.43.0.184

When I go into 'My Misty' in the app, I see Connectivity details, but no values for the fields under the 'Software' and 'Hardware' sections. I'm unsure why this is happening, but mentioning it here as I'm unsure if there is any need to mention this in the docs. Possibly more of a support issue. Feel free to have someone contact me if they want to try some more diagnostics to work it out.

Possibly related to number two above, following the steps at https://docs.mistyrobotics.com/tools-&-apps/mobile/misty-app/#updating-misty, I don't have an option in the Settings tab to update. The only options under the Misty section are 'Disconnect from Misty' and 'WiFi'.

---

For file https://github.com/MistyCommunity/Documentation/blob/master/src/content/misty-ii/robot/misty-ii.md

At https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#unpacking-your-misty-ii, when I was unpacking Misty II (and at points when I was looking underneath for the power switch, I found the head was heavy enough to swivel freely around. I wasn't (am not) sure if this is expected behaviour or not. If I hold Misty II by the base and turn it at a 30-45 degree angle, should the head be moving? If so, it might be worth mentioning that this is normal (and advise not to go too crazy shaking the robot)...

The docs at https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#wired-charging say

You can also charge Misty by plugging the power supply directly into the power port. Misty's power port is on the bottom of Misty, next to her power switch.

But, the barrel power connector is a different size and doesn't fit. It was suggested that I'm trying to plug in the wireless charger power supply, and that I probably don't have the standalone power supply, and that they are different barrel sizes on purpose because they are very different voltages. The guide suggests there is a "charging station AC power supply", and I received on AC adapter, so perhaps this should be explained.

At https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#wireless-charging step one instructs how to connect the AC adapter. When I received mine, it was already connected. Unsure what the norm here of it will vary, but might be worth noting.

When I placed Misty II on the wireless charging pad I didn't expect to hear fans whirr up. I've since been told that they will be on for as long as Misty is charging. It would probably be worth noting that after/around step five of https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#wireless-charging

Related to 2), but at at https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#wired-charging it indicates I can use the AC adapter to charge Misty II directly, when I can't with what was supplied. Some clarification might be needed if I am meant to buy/have a different AC adapter

At https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#hardware-notifications it talks about working out whether Misty II is charging or charged based on the mode of the orange LED. It would be nice to be have an idea how long charging should take. It would also be nice if there was some kind of indication (progress bar or percentage on Misty's eye display? How rapidly Misty blinks?)

I know this is pedantic, but when you asked for feedback I said I might be :).

The spelling of Wi-Fi is:

• "Wifi" in the app error (in the first section above where I was getting one)
• "WiFi" at https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#connectivity
• "Wi-Fi" at https://docs.mistyrobotics.com/misty-ii/robot/misty-ii/#connecting-to-wi-fi and throughout https://docs.mistyrobotics.com/tools-&-apps/mobile/misty-app/#connecting-misty-to-bluetooth-and-wi-fi

infinitely recursing links

Summary and proposed solution

I have an old URL into the REST API documentation that is no longer valid: https://docs.mistyrobotics.com/apis/api-reference/rest/#changedisplayimage

The new "Misty Docs" page is shown without changing the URL in the navigator. This leads to broken relative links in the page.

This error matters because old URLs might still be out there on the Web, so you should indicate via HTTP that the page moved. E.g., return 301 and the new URL. I understand if you think that it is not worth the effort to define a redirect rule for every old URL. In that case, at least provide a catch-all redirect to the new "Misty Docs" homepage, which will yield a correct URL in the user's navigator.

Example

Visit https://docs.mistyrobotics.com/apis/api-reference/rest/#changedisplayimage, then try to follow the links "On-Robot JavaScript API Architecture" or "REST API & WebSocket Architecture". You should arrive at the same page but with parts added to the URL path. Following the links again leads to more parts added to the URL while arriving back at the same page.