Merge pull request #168 from ibmtjbot/dev

Dev

.gitignore

@@ -0,0 +1,125 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# .DS_Store files
+.DS_Store
+
+# config.js files
+config.js
+
+# ibm-credentials.env files
+ibm-credentials.env

MAINTAINERS.md

@@ -1,9 +1,9 @@
 # Maintainers
+TJBot is maintained by [Justin Weisz](https://github.com/jweisz).
 
-## Core Team
-- [Maryam Ashoori](https://github.com/maryamashoori)  
-- [Victor Dibia](https://github.com/victordibia)  
-- [Justin Weisz](https://github.com/jweisz)  
+## Alumni
+TJBot was created with ❤️ at IBM Research. Many of the people on the original team have moved on to new adventures.
 
-## Other Contributors
-- [Bruno Braga](https://github.com/bgbraga)
+- [Maryam Ashoori](https://github.com/maryamashoori)
+- [Aaron Cox](https://www.linkedin.com/in/aaron-cox-532758121/)
+- [Victor Dibia](https://github.com/victordibia)

README.md

@@ -18,42 +18,51 @@ You can make your own TJBot in a number of ways.
 There are a number of components you can add to TJBot to bring him to life. Not all of these are required for all recipes.
 
 - [Raspberry Pi 3 + SD card preloaded with NOOBS](https://www.amazon.com/Vilros-Raspberry-Complete-Starter-Clear/dp/B01CUMNIV8/). **This is a required component to make TJBot work!** 🤖
-- [NeoPixel RGB LED (8mm)](https://www.adafruit.com/product/1734). Note that if you are using other kinds of LEDs, you may need to add a resistor; this LED doesn’t require one.
+- LED. We recommend the [NeoPixel RGB LED (8mm)](https://www.adafruit.com/product/1734), although TJBot supports Common Anode LEDs as well. Note that if you are not using a NeoPixel LED, you may also need to add resistors between it and the Raspberry Pi. Neopixel LEDs do not require resistors.
 - [Female-to-female jumper wires](https://www.amazon.com/dp/B00KOL5BCC/). TJBot will only need 3 of these wires, so you’ll have extra.
 - [Female-to-male jumper wires](https://www.amazon.com/dp/B00PBZMN7C/). TJBot will only need 3 of these wires, so you’ll have extra.
 - [USB Microphone](https://www.amazon.com/gp/product/B00IR8R7WQ/). Other brands of USB microphones should also work.
-- Mini Bluetooth Speaker. Any small speaker with either a 3.5mm audio jack or Bluetooth will work. Note that if you are using the 3.5mm audio jack, you may wish to add a [USB Audio Adapter](https://www.adafruit.com/product/1475) to avoid audio interference with the LED.
+- Mini Speaker. We recommend any small speaker with the ability to connect to a 3.5mm audio jack. We've had much success with the [Anker Mini Bluetooth Speaker](https://www.anker.com/uk/products/variant/pocket-bluetooth-speaker/A7910011), although this product has been discontinued as of 2018. For the best audio experience, we recommend using a [USB Audio Adapter](https://www.adafruit.com/product/1475) to avoid audio interference with the LED and to avoid difficulties in making Bluetooth speakers work reliably.
 - [Servo Motor](https://www.amazon.com/RioRand-micro-Helicopter-Airplane-Controls/dp/B00JJZXRR0/). Note that the red (middle) wire is 5v, the brown wire is ground, and the orange wire is data.
 - [Raspberry Pi Camera](https://www.amazon.com/dp/B01ER2SKFS/). Either the 5MP or 8MP camera will work.
 
 ## Assembly
 Once you have obtained your TJBot, please refer to [the assembly instructions](http://www.instructables.com/id/Build-TJ-Bot-Out-of-Cardboard/) to put it all together.
 
-For reference, here is the wiring diagram to hook up the LED and servo to your Raspberry Pi.
+For reference, here is the wiring diagram to hook up a Neopixel LED and servo to your Raspberry Pi.
 
 ![](images/wiring.png)
 
+TJBot expects LEDs and servos to be connected to a specific set of pins, including voltage (+3.3v or +5v), ground, and data. See [https://pinout.xyz](https://pinout.xyz) for a complete pin diagram. The table below shows the default pins expected for different components, although these pin numbers can be overridden in TJBot's configuration.
+
+| Component | GPIO PIN(s) | Physical PIN(s) |
+|---|---|---|
+| Neopixel LED (data pin) | GPIO 18 | Physical 12 |
+| Common Anode LED (red/green/blue) | GPIOs 19/13/12 | Physical 35/33/32 |
+| Servo (data pin) | GPIO 7 | Physical 26 |
+
 > 💡 Be careful when connecting the LED! If it is connected the wrong way, you may end up burning it out. The LED has a flat notch on one side; use this to orient the LED and figure out which pin is which.
 
-> For the servo, note that the red (middle) wire is 5v, the brown wire is ground, and the orange wire is data.
+> 👋 For the servo, note that the red (middle) wire is +5v, the brown wire is ground, and the orange wire is data.
 
 # Bring TJBot to Life
-First, make sure you have configured your Raspberry Pi for TJBot.
-Just run that command to download and install TJBot:
+First, configure your Raspberry Pi for TJBot by running the bootstrap script.
 
-```
-curl -sL http://ibm.biz/tjbot-bootstrap | sudo sh -
-```
+    curl -sL http://ibm.biz/tjbot-bootstrap | sudo sh -
 
-[Recipes](recipes) are step-by-step instructions to bring your TJBot to life with IBM Watson and AI services
+Next, take a look at TJBot's [recipes](recipes), which are pre-configured behaviors that bring TJBot to life using IBM's Watson AI services.
 
-We have provided three initial [recipes](recipes) for you:
+TJBot comes with these [recipes](recipes) to demonstrate different capabilities.
 
 - Use Your Voice to Control a Light with Watson [[instructions](http://www.instructables.com/id/Use-Your-Voice-to-Control-a-Light-With-Watson/)] [[github](https://github.com/ibmtjbot/tjbot/tree/master/recipes/speech_to_text)]
 - Make Your Robot Respond to Emotions Using Watson [[instructions](http://www.instructables.com/id/Make-Your-Robot-Respond-to-Emotions-Using-Watson/)] [[github](https://github.com/ibmtjbot/tjbot/tree/master/recipes/sentiment_analysis)]
 - Build a Talking Robot with Watson [[instructions](http://www.instructables.com/id/Build-a-Talking-Robot-With-Watson-and-Raspberry-Pi/)] [[github](https://github.com/ibmtjbot/tjbot/tree/master/recipes/conversation)]
+- Build a Robot Translator [[github](https://github.com/ibmtjbot/tjbot/tree/master/recipes/translator)]
+
+After checking out these recipes, we encourage you to take a look at [featured recipes](featured) created by members of the #tjbot community!
 
-After checking out our sample recipes, we encourage you to take a look at [featured recipes](featured) created by members of our community.
+# Troubleshooting TJBot
+Please take a look at the [troubleshooting guide](TROUBLESHOOTING.md) if you are having difficulties with TJBot.
 
 # Contribute to TJBot
 TJBot is an open source project designed to make it fun and easy to interact with [Watson](https://www.ibm.com/watson/products-services/). We’d love to see what you can make with him!

TROUBLESHOOTING.md

@@ -0,0 +1,68 @@
+# Troubleshooting TJBot
+Having difficulties making a TJBot recipe work? Please see these frequently asked questions.
+
+## Testing your TJBot's hardware
+As TJBot has a number of hardware components that may or may not be hooked up correctly, we provide an additional set of hardware tests. These tests are contained in the `tests` directory and may be run via `npm run-script`. See the [instructions for running the hardware tests](tests/README.md) for more detail.
+
+## How to debug TJBot
+TJBot uses the `winston` library to log information about its internal operation. You can adjust the log level through the `log.level` configuration parameter as follows:
+
+    const tj = new TJBot({
+        log: {
+            level: 'verbose'
+        }
+    });
+
+`winston` defines an number of logging levels, but in general the ones used by TJBot are `info` (lowest detail), `verbose` (more detail), and `silly` (highest level of detail).
+
+If you have an issue with TJBot, try increasing the log level first to see more detail as to what could be going on.
+
+## LED Issues
+
+### LED doesn't light up
+If the LED does not light up, you can try moving the power from 3.3 to 5 volts. If neither the 3.3v or 5v pins work, you will need a 1N4001 diode. The diode is inserted between the power pin of the LED (the shorter of the two middle pins) and the 5v pin on the Raspberry Pi.
+
+### LED shows the wrong color
+By default, TJBot sends colors to the LED in "RGB" format. Some LEDs may expect colors to be sent in the "GRB" format. The configuration option `shine.grbFormat` lets you switch between these two formats.
+
+    const tj = new TJBot({
+        shine: {
+            grbFormat: true
+        }
+    });
+
+### LED still shows the wrong color, rapidly flashes different colors, or flashes when audio is playing
+If the LED shows the wrong color, rapidly flashes different colors, or flashes when audio is playing, it may be due to interference with the built-in audio hardware. Depending on your configuration of Raspbian, the sound drivers may be more aggressive in taking away control of GPIO 18 from other processes. If your LED shows random colors instead of the expected color, use this trick to fix it.
+
+    $ sudo cp bootstrap/tjbot-blacklist-snd.conf /etc/modprobe.d/
+    $ sudo update-initramfs -u
+    $ sudo reboot
+
+After TJBot finishes rebooting, confirm no "snd" modules are running.
+
+    $ lsmod
+
+### LED doesn't work on Raspberry Pi 4
+There is a known issue in the `rpi-ws281x-native` library on Raspberry Pi 4 that prevents the LED from shining. There is a software workaround which involves checking out code from a special branch. As of this writing, this branch has not been merged into the main `rpi-ws281x-native` library. Within the `tjbot/recipes/speech_to_text` directory, run the following commands:
+
+    $ npm install rpi-ws281x-native@latest
+    $ git clone --single-branch --branch raspi4support https://github.com/jimbotel/rpi_ws281x.git
+    $ cp -r rpi_ws281x/* node_modules/rpi-ws281x-native/src/rpi_ws281x
+    $ npm build node_modules/rpi-ws281x-native
+
+### I'm still having troubles with the LED!
+If you have additional difficulties not covered in this guide, please refer to [Adafruit's NeoPixel on Raspbeery Pi guide](https://learn.adafruit.com/neopixels-on-raspberry-pi/overview) to troubleshoot.
+
+## Speaker issues
+
+### My Bluetooth speaker doesn't play audio
+Many people have reported numerous issues regarding Bluetooth speakers and TJBot. We **do not** recomend using a Bluetooth speaker with TJBot, as we have never reliably been able to make it work. In some instances, audio works over Bluetooth but when TJBot speaks, the speech is clipped (e.g. the first word is dropped) or garbled. In other instances, audio fails to work at all over Bluetooth, even when it works outside of TJBot (e.g. with ALSA's `aplay` command). Therefore, we recommend using a [USB audio adapter](https://www.adafruit.com/product/1475) and connecting a speaker to its 3.5mm audio jack.
+
+## Servo issues
+
+### TJBot's arm is waving backwards or upside-down
+Different models of servo may use different "stop points" to set the position of the servo. The TJBot library uses a set of stop points that work with the [RioRand SG90 9G servo](https://www.amazon.com/RioRand-micro-Helicopter-Airplane-Controls/dp/B00JJZXRR0). If these stop points don't work for your servo, try experimentally redefining the stop points defined in `TJBot.SERVO`:
+
+    TJBot.SERVO.ARM_BACK = <your stop point> // default: 500
+    TJBot.SERVO.ARM_UP = <your stop point> // default: 1400
+    TJBot.SERVO.ARM_DOWN = <your stop point> // default: 2300