Hardware Pinouts and Interfaces

Raspberry Pi

Every current model provides a 40-pin header, and each pin has the same function across models. Pins can be numbered by connector position (Physical/Board) or by CPU channel (GPIO/BCM); Grablo uses GPIO/BCM.

Apart from the power pins, every GPIO pin runs at 3.3V. The current limits are 0.5mA per input and about 8mA per output, with the sum across all output pins staying under 50mA. On the power pins, the 3.3V rail supplies about 800mA and the 5V rail about 2.5A minus what the board itself (camera, USB, and so on) and the 3.3V rail draw. The Raspberry Pi has no analog input pins, so reading an analog signal requires an ADC such as the ADS1115.

Jetson Nano

On the Jetson Nano, pin numbers and GPIO numbers are different schemes. Enter the GPIO number in Grablo.

I2C uses pins 3 (SDA) and 5 (SCK). I2C0 is reserved for internal use such as the camera interface and cannot be wired to external devices. UART is on pins 8 (TX) and 10 (RX), and its port name is /dev/ttyTHS1. PWM (pins 32 and 33) and SPI must be enabled in Jetson-IO before use: run the command below, then choose Configure Jetson 40pin header > Configure header pins manually, select the functions, save, and reboot.

sudo /opt/nvidia/jetson-io/jetson-io.py

External GPIO Adapters

When a board has no GPIO pins, or has run out of them, use a USB-GPIO adapter. See Part 6 for how to register one.

Finding an I2C Address

Registering an I/O device requires its I2C address. Running the command below in the controller's terminal lists the addresses of devices on the hardware I2C pins in hexadecimal. The bus number can differ by board.

sudo i2cdetect -y 1

The command reports addresses only, not device names or types. With several devices attached, check each device's datasheet to match addresses to devices. Devices wired to pins other than the hardware I2C pins (software I2C) cannot be found this way.

Changing the 1-Wire Pin

The Raspberry Pi's 1-Wire pin defaults to GPIO 4. To wire a device such as the DS18B20 to another pin, edit the configuration file.

sudo nano /boot/firmware/config.txt

Find dtoverlay=w1-gpio and name the pin to use. For several 1-Wire pins, write several lines. Save the file and reboot with sudo reboot to apply.

dtoverlay=w1-gpio,gpiopin=17
dtoverlay=w1-gpio,gpiopin=27

Serial (UART) Ports

Modbus and User Defined Communication need a port name. The Raspberry Pi's UARTs appear as the following devices.

The Raspberry Pi 4 has four hidden full UARTs. Add the lines you need, from dtoverlay=uart2 through uart5, to the configuration file and reboot; they appear as ttyAMA1 onward, which dmesg | grep tty confirms. The default pins are GPIO 0 and 1 for UART2, GPIO 4 and 5 for UART3, GPIO 8 and 9 for UART4, and GPIO 12 and 13 for UART5 (TXD then RXD).

Reaching the Controller and Transferring Files

These are the ways to run commands on the controller directly, or to place files such as soundfonts and AI models on it. This is a different path from the file upload used inside a project (Part 3).

Finding the Address

SSH and SFTP need the controller's hostname or IP address. The hostname set when the operating system was installed works directly; on a Raspberry Pi it defaults to raspberrypi or raspberrypi.local. Once connected, ip a reports the actual IP address. If the hostname does not resolve, scan the local network with an IP scanner.

Installing an SSH Server

Raspberry Pi OS and Debian-based distributions include an SSH server by default, but some distributions require installing it. With the controller online, run:

sudo apt-get update
sudo apt-get install -y openssh-server

Connecting over SSH

An SSH client connects to the controller and runs commands remotely. On Windows, use PuTTY; on macOS and Linux, use the ssh command in a terminal, or a client such as Termius or MobaXterm. You need the hostname or IP address, the port (22 by default), and an operating system account.

ssh username@raspberrypi.local

Transferring Files

Moving files between a PC and the controller uses SFTP. Enter the controller's hostname, login account, and port (22 by default) in an SFTP client such as FileZilla, then upload and download between the PC directory on the left and the controller directory on the right.

Automatic Login

Grablo runs as a system service, so it starts on boot without anyone logging in. Features that draw to a screen, however, such as Display Image and video playback, need a desktop session. For unattended operation with a monitor attached, turn on automatic login. On Ubuntu and Debian, open Settings > System > Users, click Unlock, and switch on Automatic Login.

Preparing External Services

Some settings need a key or value issued by an external service. Here is how to obtain each of them.

Google Cloud (TTS and STT)

1. Create a project in the Google Cloud console and attach a payment method to it under Billing.
2. Under APIs & Services, find and enable both Text-to-Speech API and Speech-to-Text API.
3. In APIs & Services > Credentials, choose + Create credentials → API key and copy the value.
4. On the same screen, restrict the key to those two APIs.This limits the damage if the key leaks.

OpenAI

1. Sign in to the OpenAI platform, create a new secret key under Dashboard > API keys, and copy the value.
2. Add a payment method and top up your balance under Settings > Billing > Payment methods.OpenAI's speech conversion has no free allowance, so a balance is required.

ElevenLabs

1. After signing up, open your account name at the bottom left, then API Keys → Create Key, and copy the value.
2. In Voices, preview the voice you want, then click View → ID to copy its Voice ID.The API key alone does not complete the setting; the Voice ID is required too.

Telegram Bot

1. Find BotFather in Telegram, start the chat, and send /newbot.
2. Enter a display name for the bot, then a username.The username must end in bot and must not collide with another bot.
3. Enter the issued token in Settings → Telegram Bot.
4. Open the new bot's link to start a chat and press START.Without this step the bot cannot send you messages.
5. Find @userinfobot in Telegram and start it to learn your chat ID. Enter that value in Action → Telegram Message.

Firebase Realtime Database

1. Create a project in the Firebase console, then create a database under Realtime Database → Create Database, choosing Start in locked mode for the security rules.
2. Copy the database address shown at the top of the screen.
3. Under Authentication → Sign-in method, enable the method you want. For email and password access, enable that method and add accounts on the Users tab; for access without a login, enable Anonymous.
4. Copy the web API key from Project settings > General.
5. On the Rules tab of Realtime Database, replace the rules with the following and publish.A database created in locked mode is closed to everyone. These rules open it to the users you allowed above.

{
  "rules": {
    ".read": "auth != null",
    ".write": "auth != null"
  }
}

Choosing an Instrument from a SoundFont

The Synthesizer setting takes a SoundFont file plus the bank and preset numbers that identify an instrument. Those numbers come from a SoundFont editor. Open the SoundFont (sf2, sf3) in an editor such as Polyphone, select an instrument in the Presets list, check the sound with the virtual keyboard, and enter the bank and preset values shown at the bottom of the screen.

Fetching Weather Data

Grablo has no dedicated weather action, so a weather API is called with the HTTP Communication action. With WeatherAPI.com, for example, sign up, find the API key on the dashboard, and request the following.

https://api.weatherapi.com/v1/forecast.json?key=API_KEY&q=Seoul&days=3&lang=en

q takes a city name, a latitude and longitude, or auto:ip; days is the number of forecast days and lang the response language. The values most often used from the response are below; extract them with the JSON blocks and store them in variables (Part 8).

Electronics Basics

What to know before wiring a device.

Digital Input and Output

In a digital circuit, current flows when the switch closes and stops when it opens. The closed state is HIGH and the open state is LOW. A digital input is the controller sensing that opening and closing on an external switch; a digital output is the controller driving it.

Analog Signals and ADCs

Values that vary continuously, such as light level or sound volume, are analog signals. The controller only handles digital signals, so reading an analog signal needs an ADC (Analog-Digital Converter) and producing one needs a DAC. The Raspberry Pi has no analog input pins, so register an ADC device such as the ADS1115 as an I/O device.

Calculating an LED Resistor

When the supply voltage is higher than the LED's forward voltage, a resistor must limit the current. Without one, current far above the rating flows and the LED is damaged. Ohm's law gives the value.

R = (supply voltage - LED forward voltage) / current

For a red LED with a 2V forward voltage on a 3.3V GPIO, allowing for the Raspberry Pi's per-pin output limit of about 8mA and targeting 5mA, the result is about 260Ω. The commonly available 220Ω gives about 5.9mA, comfortably within range. The resistor may go on either leg of the LED.

Pull-up and Pull-down Resistors

With a push button released, an input pin connected to neither the supply nor ground is neither HIGH nor LOW but floating. In that state, noise or static can flip the value arbitrarily and it cannot be controlled. A pull-up resistor pins the released state to HIGH and a pull-down resistor pins it to LOW, removing the problem.

Converting Between 3.3V and 5V

Raspberry Pi GPIO runs at 3.3V. Connecting a 5V-only sensor, or a 5V board such as an Arduino Uno, requires level conversion; connecting 5V without it damages the board.

• Voltage divider: Two resistors lower the voltage. To bring 5V down to 3.3V, for example, R1 of 1kΩ with R2 of 2kΩ produces about 3.3V. Use this for incoming 5V signals such as the echo pin of an HC-SR04 ultrasonic sensor.
• Logic level converter: A module supporting bidirectional conversion across several channels. Use it for two-way signals such as communication lines, wiring the higher voltage to HV and the lower to LV.

Raspberry Pi, Jetson Nano, and the Arduino Due and Zero are 3.3V devices; the Arduino Uno, Nano, and Mega are 5V devices.

Serial Communication Standards

Motors and Relays

DC motors are controlled by voltage for speed, servo motors by a PWM signal for angle, and stepper motors by pulse count for rotation. All three are supported as I/O devices (Part 7).