4 ⌨️ Board Configuration
"Who loves fried chips?" 🍟
Quick Software Setup Guide

4.1. NyBoard

4.1.1. Read the user manual

Find the version info on NyBoard. Read the user manual for NyBoard V1_0 or NyBoard V1_1 (a light revision).
NyBoard V1_0 Top side
NyBoard V1_0 Bottom side
Wrong operations may damage your NyBoard!

4.1.2. Dial the slide switch to Arduino.

The slide switch changes the master of I2C devices (gyro/accelerometer, servo driver, external EEPROM). On default “Arduino”, NyBoard uses the onboard ATmega328P as the master chip; On “Pi”, NyBoard uses external chips connected through the I2C ports (SDA, SCL) as the master chip.
Sometimes if you cannot go through the bootup stage, maybe you have accidentally dialed the switch to "Pi".
NyBoard powers the metal-geared servos directly with the 7.2V battery. It's 8.4V when fully charged. You CANNOT use NyBoard to drive your own plastic geared servos directly.

4.2. Downloads and installations

You will need the newest Arduino IDE to set up the environment. Older versions tend to compile larger hex files that may exceed the memory limit.
If​ you have previously added other libraries and see an error message "XXX library is already installed", ​​​​I would recommend you delete them first (instruction:​​ https://stackoverflow.com/questions/16752806/how-do-i-remove-a-library-from-the-arduino-environment). Due to different configurations of your Arduino IDE installation, if you see any error messages regarding missing libraries during later compiling, just google and install them to your IDE.
If you downloaded the newest OpenCat code from GitHub after Jan 3, 2022, you can skip all the following libraries.

4.2.1. Install through the library manager

Go to the library manager of Arduino IDE (instruction: https://www.arduino.cc/en/Guide/Libraries), search and install
  • Adafruit PWM Servo Driver
  • QList (optional)
  • IRremote
The IRremote library was updated recently. And for some reason, they even changed the encoding of the buttons. You MUST roll back the library's version to 2.6.1 in the library manager.
To save programming space, you MUST comment out the unused decoder in IRremote.h. It will save about 10% flash!
Find Documents/Arduino/libraries/IRremote/src/IRremote.h and set unused decoders to 0. That is, only DECODE_NEC and DECODE_HASH are set to 1, and others are set to 0.
#define DECODE_RC5 0
#define SEND_RC5 0
#define DECODE_RC6 0
#define SEND_RC6 0
#define DECODE_NEC 1
#define SEND_NEC 0
#define DECODE_SONY 0
#define SEND_SONY 0
set zeros all the way down the list
#define DECODE_HASH 1 // special decoder for all protocols

4.2.2 Install by adding .ZIP library

Go to jrowberg/i2cdevlib: I2C device library collection for AVR/Arduino or other C++-based MCUs, download the zip file, and unzip. You can also git clone the whole repository.
Write a caption​
Use Add .ZIP Library to find Arduino/MPU6050/ and Arduino/I2Cdev/. Click on the folders and add them one by one.​ They don’t have to be .ZIP files.​
Write a caption​​
Write a caption​

4.2.3. Add NyBoard support to Arduino IDE

With NyBoard V1_*, you can simply choose Arduino Uno.
Only if the bootloader of NyBoard collapsed, which is very unlikely to happen

4.2.4. Burn the bootloader (no need for normal use)

Every NyBoard has to go through functionality checks before shipping, so they should already have a compatible bootloader installed. However, in rare cases, the bootloader may collapse then you won't be able to upload sketches through Arduino IDE.
Well, it's not always the bootloader if you cannot upload your sketch:
  • Sometimes your USB board will detect a large current draw from a device and deactivate the whole USB service. You will need to restart your USB service, or even reboot your computers;
  • You need to install the driver for the FTDI USB 2.0 to the UART uploader;
  • You haven't selected the correct port;
  • Bad contacts;
  • Bad luck. Tomorrow is another day!
If you really decide to re-burn the bootloader:
  • With NyBoard V1_*, you can simply choose Arduino Uno under the Tool menu of Arduino IDE.
  • Select your ISP (In-System Programmer). The above screenshot shows two popular programmers: the highlighted USBtinyISP is a cheap bootloader you can buy, while the checked Arduino as ISP can let you use a regular Arduino as ISP!
  • Connect the programmer with the SPI port on NyBoard. Notice the direction when connecting. Make sure they have good contact.
  • Burn bootloader. If it's your first time doing so, wait patiently until you see several percent bars reach 100% and no more messages pop up for one minute.

4.2.5. Connect the uploader (sometimes referred to as the programmer)

Connect your computer with the uploader through USB to micro-USB cable. The uploader has three LEDs, power, Tx, and Rx. Right after the connection, the Tx and Rx should blink for one second indicating initial communication, then dim. Only the power LED should keep lighting up. You can find a new port under Tool->Port as “/dev/cu.usbserial-xxxxxxxx” (Mac) or “COM#” (Windows).
For Linux, once the uploader is connected to your computer, you will see a “ttyUSB#” in the serial port list. But you may still get a serial port error when uploading. You will need to give the serial port permission. Please go to this link and follow the instructions: https://playground.arduino.cc/Linux/All/#Permission​
If Tx and Rx keep lighting up, there’s something wrong with the USB communication. You won’t see the new port. It’s usually caused by overcurrent protection by your computer, if you’re not connecting NyBoard with an external power supply and the servos move all at once.
If you cannot find the serial port after connecting to your computer, you may need to install the driver for the CH340 chip.

4.2.6. Connect Bluetooth uploader (optional)

It’s possible to program and communicate with Bittle wirelessly. You can even control Bittle with a smartphone APP or web API from there!
We include our official Bluetooth dongle in the standard Bittle kit. It can be used for wirelessly uploading sketches and communicating with the robot. The baud rate is set to 115200.
You need to connect it to your computer like what you do with a Bluetooth AirPod. The default passcode is 0000 or 1234. Then you can select it under Tools->Port of Arduino IDE, and use it in the same way as the wired uploader.
On Mac, the Bluetooth may lose connection after several uploads. In that case, delete the connection and reconnect to resume the functionality.
The Bluetooth dongle is not included in the kit sold by Seeed Studio or its partners. Please write to [email protected] for more information.

4.2.7. Download the OpenCat package

We keep updating the codes as an open-source project. You can star and follow our GitHub repository to get the newest features and bug fixes. You can also share your codes with worldwide OpenCat users.
  • Download a fresh ​OpenCat repository from GitHub: https://github.com/PetoiCamp/OpenCat. It’s better if you utilize GitHub’s version control feature. Otherwise, make sure you download the WHOLE OpenCat FOLDER every time. All the codes have to be the same version to work together.
  • If you download the Zip file of the codes, you will get an OpenCat-main folder after unzipping. You need to rename it to OpenCat before opening the OpenCat.ino.
No matter where you save the folder, the file structure should be:
  • There are several testX.ino codes in ModuleTests folder. You can upload them to test certain modules separately. Open any testX.ino sketch with prefix “test”. (I recommend using testBuzzer.ino as your first test sketch)
  • Open up the serial monitor and set up the baud rate. With NyBoard V1_*, choose the board as Arduino Uno and later set the baud rate to 115200 in both the code and the serial monitor.
  • Compile the code. There should be no error messages. Upload the sketch to your board and you should see Tx and Rx LEDs blink rapidly. Once they stop blinking, messages should appear on the serial monitor.
  • Make sure you set "No line ending" to before entering your commands. Otherwise, the invisible '\n' or '\r' characters will confuse the parsing functions.
For Linux machines, you may see the error message like "permission denied". You will need to add execution privilege to the avr-gcc to compile the Arduino sketch:sudo chmod +x filePathToTheBinFolder/bin/avr-gcc
Furthermore, you need to add execution permission to all files within /bin, so the command would be : sudo chmod -R +x /filePathToTheBinFolder/bin

4.3. Arduino IDE as an interface

With the USB/Bluetooth uploader connecting NyBoard and Arduino IDE, you have the ultimate interface to communicate with NyBoard and change every byte on it.
I have defined a set of serial communication protocol for NyBoard:
All the token starts with a single Ascii encoded character to specify its parsing format. They are case-sensitive and usually in lower case.
Some commands, like the c and m commands can be combined.
For example:
Successive "m8 40", "m8 -35", "m 0 50" can be written as "m8 40 8 -35 0 50". You can combine up to four commands of the same type. To be exact, the length of the string should be smaller than 30 characters. You can change the limit in the code but there might be a systematic constraint for the serial buffer.
Some tokens haven't been implemented, such as 'h'.

4.4. Raspberry Pi serial port as an interface

Only when using Pi as a master controller. Bittle doesn't need a Pi to move.
You can solder a 2x5 socket on NyBoard to plug in a Raspberry Pi. Pi 3A+ is the best fit for Bittle's dimension.
After you solder on the socket, you won't be able to install the back cover of Bittle.
You need to unplug the 6-pin programmer for the NyBoard before mounting the Pi to the board.
The red Pi standoff can be 3D printed.
As shown in the serial protocol, the arguments of tokens supported by Arduino IDE's serial monitor are all encoded as Ascii char strings for human readability. While a master computer (e.g. RasPi) supports extra commands, mostly encoded as binary strings for efficient encoding. For example, when encoding angle 65 degrees:
  • Ascii: takes 2 bytes to store Ascii characters '6' and '5'
  • Binary: takes 1 byte to store value 65, corresponding to Ascii character 'A'
What about value -113? It takes four bytes as an Ascii string but still takes only one byte in binary encoding, though the content will no longer be printable as a character.
Obviously, binary encoding is much more efficient than the Ascii string. However, the message transferred will not be directly human-readable. In the OpenCat repository, I have put a simple Python script ardSerial.py that can handle the serial communication between NyBoard and Pi.

4.4.1. Config Raspberry Pi serial port

In Pi's terminal, type sudo raspi-config
Under the Interface option, find Serial. Disabled the serial login shell and enable the serial interface to use the primary UART:
  1. 1.
    Run raspi-config with sudo privilege: sudo raspi-config.
  2. 2.
    Find Interface Options -> Serial Port.
  3. 3.
    At the option Would you like a login shell to be accessible over serial? select 'No'.
  4. 4.
    At the option Would you like the serial port hardware to be enabled? select 'Yes'.
  5. 5.
    Exit raspi-config and reboot for changes to take effect.
You also need to DISABLE the 1-wire interface of Pi to avoid repeating reset signals sent by Pi's GPIO 4.
If you plug Pi into NyBoard's 2x5 socket, their serial ports should be automatically connected at 3.3V. Otherwise, pay attention to the Rx and Tx pins on your own AI chip and its voltage rating. The Rx on your chip should connect to the Tx of NyBoard, and Tx should connect to Rx.
Note: If you installed Ubuntu OS on Raspberry Pi, please config it as follows:
  • add enable_uart=1 to /boot/config.txt
  • remove console=serial0,115200 from /boot/firmware/cmdline.txt on Ubuntu and similar to/boot/cmdline.txt on Raspberry Pi OS
  • disable the serial console: sudo systemctl stop [email protected] && sudo systemctl disable [email protected]
  • make sure you have pyserial installed if you're using the python serial library, not python-serial from apt.
  • create the following udev file (I created /etc/udev/rules.d/50-tty.rules):
KERNEL=="ttyS0", SYMLINK+="serial0" GROUP="tty" MODE="0660"
KERNEL=="ttyAMA0", SYMLINK+="serial1" GROUP="tty" MODE="0660"
  • reload your udev rules: sudo udevadm control --reload-rules && sudo udevadm trigger
  • change the group of the new serial devices:
sudo chgrp -h tty /dev/serial0
sudo chgrp -h tty /dev/serial1
  • The devices are now under the tty group. Need to add the user to the tty group and dialout group:
sudo adduser $USER tty
sudo adduser $USER dialout
  • update the permissions for group read on the devices:
sudo chmod g+r /dev/ttyS0
sudo chmod g+r /dev/ttyAMA0
  • reboot
Or just create a script that will do this automatically.

4.4.2. Change the permission of ardSerial.py​

If you want to run it as a bash command, you need to make it executable:
chmod +x ardSerial.py
You may need to change the proper path of your Python binary on the first line:

4.4.3. Use ardSerial.py as the commander of Bittle

NyBoard has only one serial port. You need to UNPLUG the FTDI converter if you want to control Bittle with Pi's serial port.
Typing ./ardSerial.py <args> is almost equivalent to typing <args> in Arduino's serial monitor. For example, ./ardSerial.py kcrF means "perform skill crawl Forward".
Both ardSerial.py and the parsing section in OpenCat.ino need more implementations to support all the serial commands in the protocol.

4.5. Battery

Though you can program NyBoard directly with the USB uploader, external power is required to drive the servos.

4.5.1. Voltage

NyBoard requires 7.4~8.4V external power to drive the servos. We include our customized Li-ion battery with built-in charging and protection circuit in the Bittle kit. Short press the battery's button will show its status. Blue light indicates it has power, and red means the power is low.

4.5.2. Connection and Power On

Be careful with the polarity when connecting the power supply. The terminal on NyBoard has an anti-reverse socket, so you won't be able to plug in the wrong direction. See here for the detailed connection instruction.
Please long press the button of the battery for 3 seconds to power on the battery.
Reversed connection may damage your NyBoard!

4.5.3. Battery life varies according to usage

It can last hours if you're mainly coding and testing postures, or less than 30 mins if you keep Bittle running.
The battery light will turn red when the power is low. The power will be cut off automatically.

4.5.4. Charging

Use a 5V-1A USB charger to charge the battery. We don't recommend using fast chargers. The battery will NOT supply power during charging. Keep the battery in your sight when charging.

4.5.5. After use

After playing, remember to turn off the battery. It's recommended to unplug the battery from the NyBoard's terminal.