Merge pull request #5 from opheliasdaisies/docs

Initial setup documentation
nodebots · Aug 13, 2018 · cd3c08f · cd3c08f
2 parents a7ecbe0 + 6a27ad8
commit cd3c08f
Show file tree

Hide file tree

Showing 14 changed files with 2,115 additions and 14 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+.DS_Store
+*.swp
diff --git a/README.md b/README.md
@@ -4,18 +4,28 @@
 
 As part of this workshop, you should divide up into teams of 3-4 people. Try to find people with a similar boat "vision" as you to partner with.
 
-There will be two different boat models that each team can make as part of the NodeBoats workshop. One is a motor-propelled boat, and the other is a paddle boat. Each kit should have all supplies needed for either type of boat! Keep in mind that the motor-propelled boat does require some soldering, so keep this in mind when deciding which kind of propulsion you want for your boat!
+Teams will be building a motor-propelled boat, which will require some soldering. Feel free to ask any of the workshop team members if you need help with any part of this process.
 
 Each boat kit will include the following materials. Make sure you let us know if any components are missing! (Please also keep in mind that we do need the parts back at the end of the day!)
 
 #### Boat Kits
-- TBD
-- TBD
-- TBD
-- TBD
-- TBD
+
+- Arduino Nano
+- Electronic Speed Controller (ESC) 30A with Reverse
+- Micro Servo
+- HC-06 Bluetooth Module
+- 2S Lipo Battery with XT60 connector
+- 2S USB Lipo Charger
+- Breadboard
+- USB A <-> Mini-B USB cable
+- Jumper Wires (Male-to-Male && Female-to-Male)
+- Wire Extension
+- Brushless Motor
+- Propellor
+- L-shaped connector
 
 #### Things you may need (And We Have!!!)
+
 - Goopy goo glue sealant
 - Styrofoam (we have sheets and will cut off what your boat needs)
 - Popsicle Sticks!
@@ -27,16 +37,161 @@ Each boat kit will include the following materials. Make sure you let us know if
 - Box cutters
 - Googly eyes
 
+### Configuring the Arduino Nano & HC-06 Bluetooth module
+
+To avoid using extemely long USB cables to drive the boats from the water to your laptops, the HC-06 Bluetooth module will allow you to run Johnny-Five commands wirelessly to the Arduino Nano. The Nodeboats team has pre-configured the modules to do this, so the following instructions are useful if you are building the boat at home later or need to reconfigure the module. They are based on the [HC-05 configuration docs](https://github.com/rwaldron/johnny-five/wiki/Getting-Started-with-Johnny-Five-and-HC-05-Bluetooth-Serial-Port-Module) with some key changes for the HC-06 and this workshop. Skip to step 4 and 5 to learn about pairing the module with your laptop.
+
+#### Step 1: Connect the HC-05 module to the Arduino for configuration
+
+We will program the Arduino to send AT commands to the module to configure it via a SoftwareSerial connection. Wire the TX and RX pins of your module to your Arduino. They need wired in a crossover configuration, so from the module to the Arduino wire TX to pin 10 and RX to pin 11.
+
+![Arduino Nano to HC-06 Bluetooth breadboard](./diagrams/Nano-HC06-config_bb.png)
+
+You will need the [Arduino IDE](https://www.arduino.cc/en/main/software) to upload the [configuration sketch file](/code/HC06-Config/HC06-Config.ino) to your Arduino. The sketch will create a connection between the Arduino's serial port and the HC-06, as well as configure the HC-06 to use the same [baudrate](https://en.wikipedia.org/wiki/Baud) as Johnny-Five.o
+
+```c
+
+  // Set ROBOT_NAME to something unique
+  #define ROBOT_NAME "RandomBot"
+
+  // If you haven't configured your device before use this
+  #define BLUETOOTH_SPEED 9600 //This is the default baudrate that HC-06 uses
+  // If you are modifying your existing configuration, use this:
+  // #define BLUETOOTH_SPEED 57600
+
+  #include <SoftwareSerial.h>
+
+  // Swap RX/TX connections on bluetooth chip
+  //   Pin 10 --> Bluetooth TX
+  //   Pin 11 --> Bluetooth RX
+  SoftwareSerial mySerial(10, 11); // RX, TX
+
+  /*
+    The possible baudrates are:
+      AT+UART=1200,0,0 -------1200
+      AT+UART=2400,0,0 -------2400
+      AT+UART=4800,0,0 -------4800
+      AT+UART=9600,0,0 -------9600 - Default for hc-06
+      AT+UART=19200,0,0 ------19200
+      AT+UART=38400,0,0 ------38400
+      AT+UART=57600,0,0 ------57600 - Johnny-five speed
+      AT+UART=115200,0,0 -----115200
+      AT+UART=230400,0,0 -----230400
+      AT+UART=460800,0,0 -----460800
+      AT+UART=921600,0,0 -----921600
+      AT+UART=1382400,0,0 ----1382400
+  */
+
+  void setup() {
+    Serial.begin(9600);
+
+    Serial.println("Starting config");
+    mySerial.begin(BLUETOOTH_SPEED);
+    delay(1000);
+
+    // Should respond with OK
+    mySerial.print("AT\r\n");
+    waitForResponse();
+
+    // Should respond with its version
+    mySerial.print("AT+VERSION\r\n");
+    waitForResponse();
+
+    // Should respond with default password, probably 1234
+    mySerial.print("AT+PSWD\r\n");
+    waitForResponse();
+
+    // Set the name to ROBOT_NAME
+    String rnc = String("AT+NAME=") + String(ROBOT_NAME) + String("\r\n"); 
+    mySerial.print(rnc);
+    waitForResponse();
+
+    // Set baudrate to 57600
+    mySerial.print("AT+UART=57600,0,0\r\n");
+    waitForResponse();
+
+    Serial.println("Done!");
+  }
+
+  void waitForResponse() {
+      delay(1000);
+      while (mySerial.available()) {
+        Serial.write(mySerial.read());
+      }
+      Serial.write("\n");
+  }
+
+  void loop() {}
+
+```
+
+#### Step 2: Check configuration
+
+The setup() function will take about 6 seconds to run. You can connect to the Arduino with Serial Monitor and you should see the following output.
+
+```
+
+  Starting config
+  OK
+  OK[VERSION]
+  OK[PSWD]
+  OK
+  OK
+  Done!
+
+```
+
+If you saw that congratulations, you're done this step.
+
+If you see the following output instead, you will probably have to change BLUETOOTH_SPEED to another value and upload it again. This could be because the HC-06 chip had different baud rate.
+
+```
+
+  Starting config
+
+
+
+
+
+  Done!
+
+```
+
+If you are having troubles uploading the firmata firmware to the device, make sure that nothing is connected to pins 0 and 1 when uploading as this can interfere with the upload process.
+
+
+#### Step 3: Reupload StandardFirmataPlus
+
+Once the baud rate is properly set, re upload the StandardFirmataPlus sketch to your board. If you don't do this it might seems that your bluetooth module is getting a connection, the light will stop blinking, but you won't be able to connect.
+
+You can upload StandardFirmataPlus through the [Arduino IDE](https://www.instructables.com/id/Arduino-Installing-Standard-Firmata/) or using [firmata-party](https://www.npmjs.com/package/firmata-party) from the command line.
+
+#### Step 4: Wire the module to the Arduino's hardware port
+
+Once the baud rate is properly set & Firmata reloaded, connect the TX and RX pins to Arduino pins RX0 and TX1 respectively.
+
+![Arduino Nano to HC-06 hookup](./diagrams/Nano-HC06-working_bb.png)
+
+#### Step 5: Pair the module
+
+Pair to the module from your host device, once you have paired with your bluetooth device the serial port should be visible with the 'ROBOT_NAME' you used in Step 1. It will be something like /dev/tty.ROBOT_NAME-SPPDev (in UNIX) and use COMX in Windows (where X is the number of the port). Use this name to tell [Johnny-Five which port to use](http://johnny-five.io/api/board/#component-initialization).
+
+You can test the connection by modifying the `blink.js` program to add the path to the Bluetooth port and running the program. Make sure Johnny-Five is installed in the `code` directory (`npm install`) before running `node code/blink.js`. 
+
 ### Resources for Building Your Boat!
 
 You may need some help while setting up your NodeBoat. Here are some tips and tricks so you can learn from our experiences:
-- TBD
-- TBD
-- TBD
-- TBD
+
+- Check out the [build guide](./build.md) to see wiring examples and tips for working with the ESC and servo.
+- The [Arduino Nano pinout](http://www.circuitstoday.com/arduino-nano-tutorial-pinout-schematics) is a handy reference for what each pin can do
+- The name of the Bluetooth module should be on its bag, look for this when pairing it with your laptop
+- Connect the ground (GND) wire before connecting the power wire, especially when working with the lipo battery.
+- Unplugging or turning off power when switching wires is good practice to avoid unexpected short circuits.
 
 First Time Using Johnny-Five? Don't hesitate to ask us for help! That's why we're here. Here are some intro materials and parts of the docs that will be particularly helpful while building your boats:
-- TBD
-- TBD
-- TBD
-- TBD
+
+- [Board class API](http://johnny-five.io/api/board/#component-initialization)
+- [ESC class API](http://johnny-five.io/api/esc/)
+- [Servo class API](http://johnny-five.io/api/servo/)
+- [Controlling Johnny-Five with `keypress`](https://gist.github.com/goldsamantha/1fd9ba71c398e8a06fd319cac05cf022)
+- [Controlling Johnny-Five with Express & Socket.io](https://learn.sparkfun.com/tutorials/reconbot-with-the-tessel-2)
diff --git a/build.md b/build.md
@@ -0,0 +1,38 @@
+# Tips for Building The Motor-powered Nodeboat!
+
+This build does require soldering, so ask for help if you need it.
+
+In order to power the boat, the battery will connect directly to the ESC and share the power from the ESC to the breadboard. See the hookup diagram below. The battery has an XT60 connector that needs a matching connector soldered onto the ESC's red and black wires. Check out the sides of the XT60 for a plus (+) and a minus (-) sign with the red wire (power) lining up with the plus sign and the black wire (ground) lining up with the minus sign. Once the battery is hooked up to the ESC, you can use the power switch on the ESC to test the connection.
+
+The following is an example hookup for using the Electronic Speed Controller (ESC):
+![Arduino Nano to ESC hookup](./diagrams/Nano-HC06-ESC_bb.png)
+
+Pin hookup:
+
+- RXD on HC-06 <-> TX1 on Nano
+- TXD on HC-06 <-> RX0 on Nano
+- Orange wire on ESC <-> D10 on Nano
+- Every black wire goes to the ground (GND) rail
+- Every red wire goes to the power rail
+
+Adding the servo for steering is as simple as adding three more wires to the breadboard:
+![Arduino Nano with ESC and Servo hookup](./diagrams/Nano-HC06-ESC-Servo_bb.png)
+
+Pin hookup:
+
+- RXD on HC-06 <-> TX1 on Nano
+- TXD on HC-06 <-> RX0 on Nano
+- Orange wire on ESC <-> D10 on Nano
+- **Yellow wire on Servo <-> D11 on Nano**
+- Every black wire goes to the ground (GND) rail
+- Every red wire goes to the power rail
+
+The L-shaped connector included in the kit should be attached with one end on the top of the servo and the other end to the back of the motor. You can use glue, duct tape, or whatever method you'd like for attaching it.
+
+## Wiring Tips
+
+- You may notice the 5V pin on the Arduino Nano is not powering the HC-06 or any other device. This is to prevent [brownouts](https://en.wikipedia.org/wiki/Brownout_(electricity)) that can be caused by spikes in power draw from the servo or motor.
+
+## General Tips
+
+- Before drilling a hole in the boat hull to pass through the wires from the motor pod, it is strongly recommended that you put all of your components in the boat first, to test the bouyancy and add the appropriate amount of styrafoam to the boat.
diff --git a/code/HC06-Config/HC06-Config.ino b/code/HC06-Config/HC06-Config.ino
@@ -0,0 +1,71 @@
+// Set ROBOT_NAME to something unique
+#define ROBOT_NAME "RandomBot"
+
+// If you haven't configured your device before use this
+#define BLUETOOTH_SPEED 9600 //This is the default baudrate that HC-06 uses
+// If you are modifying your existing configuration, use this:
+// #define BLUETOOTH_SPEED 57600
+
+#include <SoftwareSerial.h>
+
+// Swap RX/TX connections on bluetooth chip
+//   Pin 10 --> Bluetooth TX
+//   Pin 11 --> Bluetooth RX
+SoftwareSerial mySerial(10, 11); // RX, TX
+
+/*
+  The possible baudrates are:
+    AT+UART=1200,0,0 -------1200
+    AT+UART=2400,0,0 -------2400
+    AT+UART=4800,0,0 -------4800
+    AT+UART=9600,0,0 -------9600 - Default for hc-06
+    AT+UART=19200,0,0 ------19200
+    AT+UART=38400,0,0 ------38400
+    AT+UART=57600,0,0 ------57600 - Johnny-five speed
+    AT+UART=115200,0,0 -----115200
+    AT+UART=230400,0,0 -----230400
+    AT+UART=460800,0,0 -----460800
+    AT+UART=921600,0,0 -----921600
+    AT+UART=1382400,0,0 ----1382400
+*/
+
+void setup() {
+  Serial.begin(9600);
+
+  Serial.println("Starting config");
+  mySerial.begin(BLUETOOTH_SPEED);
+  delay(1000);
+
+  // Should respond with OK
+  mySerial.print("AT\r\n");
+  waitForResponse();
+
+  // Should respond with its version
+  mySerial.print("AT+VERSION\r\n");
+  waitForResponse();
+
+  // Should respond with default password
+  mySerial.print("AT+PSWD\r\n");
+  waitForResponse();
+
+  // Set the name to ROBOT_NAME
+  String rnc = String("AT+NAME=") + String(ROBOT_NAME) + String("\r\n"); 
+  mySerial.print(rnc);
+  waitForResponse();
+
+  // Set baudrate to 57600
+  mySerial.print("AT+UART=57600,0,0\r\n");
+  waitForResponse();
+
+  Serial.println("Done!");
+}
+
+void waitForResponse() {
+    delay(1000);
+    while (mySerial.available()) {
+      Serial.write(mySerial.read());
+    }
+    Serial.write("\n");
+}
+
+void loop() {}
diff --git a/code/blink.js b/code/blink.js
@@ -0,0 +1,10 @@
+const five = require('johnny-five');
+
+const board = new five.Board({
+  port: '', // path to bluetooth connection, i.e. /dev/tty.ROBOT_NAME-SPPDev or COMX
+});
+
+board.on('ready', () => {
+  const led = new five.Led(13); // use built-in led on Arduino
+  led.blink();
+});