ROS Package tioros

TwitchIO ROS Chatbot Nodes. A ROS 2 - Twitch Chat Bridge.

Installation Prerequisites

Use the package manager pip3 to install the below dependencies.

pip3 install twitchio requests

Setup Package

# run in your ros2_ws/src folder
git clone https://github.com/bob-ros2/tioros.git
cd ..
colcon build --packages-select tioros
. install/setup.bash

Authentication Methods

There are two primary ways to authenticate with Twitch, depending on the node you are using. You can store both in a unified ~/.credentials file:

1. OAuth Flow (Traditional IRC Chatbot):

   • What is it?: A single long-living Access Token.

   • Storage: A plain text file containing just the token (e.g., oauth:xxxxxxxxxxxxx) OR a access_token field in a JSON file.

   • Usage: Standard for sending/receiving chat messages.

   • Env Var: TIOROS_TOKEN (direct token) or TIOROS_CREDENTIALS (path to file).

2. App Credentials (EventSub Node):

   • What is it?: client_id, client_secret and a refresh_token.

   • Storage: A JSON file (recommended for automation with auth.py).

   • Example .credentials (JSON):

     {
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "refresh_token": "YOUR_REFRESH_TOKEN",
       "access_token": "YOUR_CURRENT_OAUTH_TOKEN",
       "webhook_secret": "YOUR_WEBHOOK_SECRET",
       "callback_route": "https://your.callback.url/path"
     }
     

   • Usage: Required for rich events (follows, raids).

ROS Node: chatbot

Usage

# Set token directly via environment variable
export TIOROS_TOKEN=oauth:xxxxxxxxxxxxxx
ros2 run tioros chatbot --ros-args -p channel:=myTwitchTv

# Or use a credentials file (Smart Load: supports plain text or JSON field)
export TIOROS_CREDENTIALS=~/.credentials
ros2 run tioros chatbot --ros-args -p channel:=myTwitchTv

Supported TwitchIO Events

The following received Twitch events are published as std_msgs/String messages.

• event_ready: event_ready %user_id %nick

• event_join: event_join 0 %user_name (Note: User ID 0 is used to avoid Twitch API rate-limiting during high traffic)

• event_message: event_message %user_id %author_name %message_content

Node Parameters

Parameter	Type	Default	Description
channel	string	superbob_6110	Twitch channel to join. (Env: TIOROS_CHANNEL)
token	string	""	Direct Twitch Access Token. (Env: TIOROS_TOKEN)
credentials	string	~/.credentials	Path to credentials file (plain or JSON). (Env: TIOROS_CREDENTIALS)
frame_id	string	channel	Frame ID for published messages. (Env: TIOROS_FRAME_ID)
prefix	string	!	Command prefix for the bot. (Env: TIOROS_PREFIX)

Topics

• Subscribed: chat_input (std_msgs/String) - Messages to send to Twitch.

• Published: chat (std_msgs/String) - Raw chat events.

• Published: json (std_msgs/String) - Structured event data.

ROS Node: eventsub

This node uses the Twitch EventSub extension for rich event tracking (follows, raids, etc.).

Usage

export TIOROS_CREDENTIALS=~/.credentials
ros2 run tioros eventsub --ros-args \
  -p channel:=myChannelName \
  -p broadcaster_id:="'123456'"

Node Parameters

Parameter	Type	Default	Description
channel	string	superbob_6110	Twitch channel name. (Env: TIOROS_CHANNEL)
broadcaster_id	string	123456	The numeric Twitch ID of the broadcaster. (Env: TIOROS_BROADCASTER_ID)
moderator_id	string	broadcaster_id	The numeric Twitch ID of the moderator account. (Env: TIOROS_MODERATOR_ID)
credentials	string	~/.credentials	Path to JSON file with API credentials. (Env: TIOROS_CREDENTIALS)
callback_port	int	4000	Port for incoming webhook notifications. (Env: TIOROS_CALLBACK_PORT)
events_only	bool	false	If true, disables automated “Thank you” messages in chat. (Env: TIOROS_EVENTS_ONLY)
frame_id	string	channel	Frame ID for message headers. (Env: TIOROS_FRAME_ID)

Topics

• Published: eventsub (std_msgs/String) - Human-readable event string.

• Published: json (std_msgs/String) - Structured event data.

ROS Node: filter

Usage

# Use a whitelist and regex substitution
ros2 run tioros filter --ros-args \
  -r chat:=/chat_source \
  -p "substitute:=['^[^ ]+ [^ ]+ ([^ ]+) (.*)', '\\1: \\2']"

Node Parameters

Parameter	Type	Default	Description
white_filter	string array	['']	Comma-separated list for whitelist rules. (Env: TIOROS_WHITE_FILTER)
black_filter	string array	['']	Comma-separated list for blacklist rules. (Env: TIOROS_BLACK_FILTER)
white_list	string	""	Path to YAML file with whitelist regex. (Env: TIOROS_WHITE_LIST)
black_list	string	""	Path to YAML file with blacklist regex. (Env: TIOROS_BLACK_LIST)
substitute	string array	['']	Regex pairs: ['pattern1','replace1','pattern2','replace2',...]. Must be an even number of items. (Env: TIOROS_SUBSTITUTE)

Topics

• Subscribed: chat (std_msgs/String) - Incoming chat messages.

• Published: chat_filtered (std_msgs/String) - Messages passing filters.

• Published: rejected (std_msgs/String) - Blocked messages.

Tool: AUTH

Simple Twitch authentication and token management.

Usage

# Help output
ros2 run tioros auth -h

# Generate token from refresh token
ros2 run tioros auth -f ~/.credentials -r YOUR_REFRESH_TOKEN