New: NES R.O.B. Control Library

LICENSE.mit

@@ -0,0 +1,18 @@
+Copyright 2021 Zachary J. Fields
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

docs/api.md

@@ -0,0 +1,109 @@
+NesRob Library
+==============
+
+Definitions
+-----------
+
+### `Command` (enum class)
+
+The `Command` enum class specified which movements are available to R.O.B.
+
+Command List:
+
+- `CALIBRATE_MOTORS`
+
+  Runs the startup calibration routine.
+
+- `TEST_LED`
+
+  Turns on the LED on top of R.O.B.'s head.
+
+- `ARMS_LEFT`
+
+  Turn R.O.B.'s torso to the left one station [1,5].
+
+- `ARMS_RIGHT`
+
+  Turn R.O.B.'s torso to the right one station [1,5].
+
+- `ARMS_LOWER`
+
+  Lower R.O.B.'s arms one notch (on back of spine) [1,6].
+
+- `ARMS_LOWER_2`
+
+  Lower R.O.B.'s arms two notches (on back of spine) [1,6].
+
+- `ARMS_RAISE`
+
+  Raise R.O.B.'s arms one notch (on back of spine) [1,6].
+
+- `ARMS_RAISE_2`
+
+  Raise R.O.B.'s arms two notches (on back of spine) [1,6].
+
+- `HANDS_CLOSE`
+
+  Brings R.O.B.'s hands together.
+
+- `HANDS_OPEN`
+
+  Spreads R.O.B.'s hands apart.
+
+Methods
+-------
+
+### `NesRob(unsigned int)` (constructor)
+
+Requires a pin number argument to creates the NesRob instance.
+
+#### Syntax
+
+```
+NesRob rob(13);
+```
+
+#### Parameters
+
+* _pin_: the pin used to drive the LED
+
+#### Example
+
+```c++
+#include <NesRob.h>
+
+NesRob rob;
+```
+### `blinkCommand(Command)`
+
+Manipulates R.O.B. by blinking the signal related to the `Command` provided to
+the API.
+
+#### Syntax
+
+```
+rob.blinkCommand(NesRob::Command::HANDS_CLOSE);
+```
+
+#### Parameters
+
+* _command_: a bit array used to indicate the flash pattern
+
+#### Example
+
+```c++
+#include <NesRob.h>
+
+NesRob rob;
+
+void setup() { }
+
+void loop() {
+  rob.blinkCommand(NesRob::Command::HANDS_CLOSE);
+  delay(1000);
+}
+```
+
+#### See also
+
+* [`Command` enum class](#command-enum-class)

docs/readme.md

@@ -0,0 +1,42 @@
+NES R.O.B. Control Library
+==========================
+
+This library allows an Arduino board to control the Nintendo Entertainment
+System Robot Operating Buddy (R.O.B.). This library has borrowed the research
+done by x87bliss and those on the
+[Atari Age Forums](https://atariage.com/forums/topic/177286-any-interest-in-nes-rob-homebrews/),
+as well as
+[Anne Barela's work](https://learn.adafruit.com/controlling-a-classic-nintendo-r-o-b-robot-using-circuit-playground-express/overview)
+at Adafruit.
+
+The NesRob library simplies the interaction with the NES R.O.B. by handling the
+precision timing and command processing necessary to control R.O.B. The end user
+can simply choose an LED pin, then supply any of R.O.B.'s available actions to
+invoke the specified behavior in R.O.B. This library operates on top of the
+Arduino API, and therefore should be available to any Arduino compatible device.
+
+To use this library:
+
+```c++
+#include <NesRob.h>
+
+NesRob rob;
+
+void setup() { }
+
+void loop() {
+  rob.blinkCommand(NesRob::Command::HANDS_CLOSE);
+  delay(1000);
+}
+```
+
+[API Documentation](api.md)
+---------------------------
+
+_Click the title to view the API documentation page._
+
+Examples
+--------
+
+* [CloseHands](https://www.github.com/zfields/nes-rob/tree/main/examples/CloseHands/CloseHands.ino):
+Validate your hardware configuration by sending a simple command to R.O.B.

examples/CloseHands/CloseHands.ino

@@ -0,0 +1,37 @@
+/*
+  Close R.O.B.'s Hands
+
+  Turns on and off a light emitting diode (LED) connected to a digital pin to
+  send control signals to the NES R.O.B. When R.O.B. is powered on, it executes
+  a calibration routine, which leaves it facing forward with hands open. This
+  sketch causes R.O.B.'s hands to close, validating your hardware configuration.
+
+  The circuit:
+  - Use the onboard LED (may require a brighter LED if the room is too bright).
+  - Note: Most Arduinos have an on-board LED you can control. On the UNO, MEGA
+    and ZERO it is attached to digital pin 13, on MKR1000 on pin 6. LED_BUILTIN
+    is set to the correct LED pin independent of which board is used.
+    If you want to know what pin the on-board LED is connected to on your
+    Arduino model, check the Technical Specs of your board at:
+    https://www.arduino.cc/en/Main/Products
+
+  created 2021
+  by Zachary J. Fields
+
+  This example code is in the public domain.
+  http://www.github.com/zfields/nes-rob
+*/
+
+#include "NesRob.h"
+
+NesRob rob(LED_BUILTIN);
+
+void setup() {
+  // put your setup code here, to run once:
+}
+
+// Blink command at 1 Hz
+void loop() {
+  rob.blinkCommand(NesRob::Command::HANDS_CLOSE);
+  delay(1000);
+}

keywords.txt

@@ -0,0 +1,33 @@
+#######################################
+# Syntax Coloring Map NesRob
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+blinkCommand	KEYWORD2
+Command	KEYWORD2
+
+#######################################
+# Structures (KEYWORD3)
+#######################################
+NesRob	KEYWORD3
+
+#######################################
+# Constants (LITERAL1)
+#######################################
+
+CALIBRATE_MOTORS	LITERAL1
+TEST_LED	LITERAL1
+ARMS_LEFT	LITERAL1
+ARMS_RIGHT	LITERAL1
+ARMS_LOWER	LITERAL1
+ARMS_LOWER_2	LITERAL1
+ARMS_RAISE	LITERAL1
+ARMS_RAISE_2	LITERAL1
+HANDS_CLOSE	LITERAL1
+HANDS_OPEN	LITERAL1

library.properties

@@ -0,0 +1,10 @@
+name=NesRob
+version=1.0.0
+author=Zachary J. Fields
+maintainer=Zachary J. Fields <[email protected]>
+sentence=Manipulates LED to signal NES R.O.B. (Robot Operating Buddy)
+paragraph=This class attaches to a specified LED, and is capable of generating the control signals required to invoke R.O.B.
+category=Device Control
+url=http://www.github.com/zfields/nes-rob
+architectures=*
+includes=NesRob.h

src/NesRob.h

@@ -0,0 +1,34 @@
+#ifndef NES_ROB_H
+#define NES_ROB_H
+
+#include <cstdint>
+
+class NesRob {
+  public:
+  enum class Command : uint8_t {
+    CALIBRATE_MOTORS = 0xAB,
+    TEST_LED = 0xEB,
+    ARMS_LEFT = 0xBA,
+    ARMS_RIGHT = 0xEA,
+    ARMS_LOWER = 0xFB,
+    ARMS_LOWER_2 = 0xAE,
+    ARMS_RAISE = 0xFA,
+    ARMS_RAISE_2 = 0xBB,
+    HANDS_CLOSE = 0xBE,
+    HANDS_OPEN = 0xEE,
+  };
+
+  NesRob (
+    unsigned int led_pin
+  );
+
+  void
+  blinkCommand(
+    Command command
+  );
+
+  private:
+  const unsigned int _led_pin;
+};
+
+#endif // NES_ROB_H

src/NesRob_Arduino.cpp

@@ -0,0 +1,36 @@
+#include "NesRob.h"
+
+#include <Arduino.h>
+
+NesRob::NesRob (
+  unsigned int led_pin_
+) :
+  _led_pin(led_pin_)
+{
+  ::pinMode(_led_pin, OUTPUT);
+  ::digitalWrite(_led_pin, LOW);
+}
+
+void
+NesRob::blinkCommand (
+  Command command_
+) {
+  // Send initialization sequence
+  ::delayMicroseconds(66666); // 0000 (required delay between commands)
+  {
+    ::digitalWrite(_led_pin, HIGH);
+    ::delayMicroseconds(1500);
+    ::digitalWrite(_led_pin, LOW);
+    ::delayMicroseconds(15166);
+  } // 1
+  ::delayMicroseconds(16666); // 0
+
+  // Flash command sequence
+  for (int i = 7 ; i >= 0 ; --i) {
+    unsigned int state = ((static_cast<unsigned int>(command_) >> i) & static_cast<unsigned int>(0x1));
+    ::digitalWrite(_led_pin, (state ? HIGH : LOW));
+    ::delayMicroseconds(1500);
+    ::digitalWrite(_led_pin, LOW);
+    ::delayMicroseconds(15166);
+  }
+}