Wiznet makers

Open-Source Animatronic Puppet Control System with Distributed Network Nodes

A Linux-based system brings puppets to life by synchronizing servo movements with audio. ESP32 network nodes with W5500 Ethernet enable scalable, real-time control of hundreds of servos and relays across distributed installations.

PROJECT DESCRIPTION

1. Project Background and Technical Goals

This project was initiated to solve a fundamental challenge in animatronics: synchronizing complex servo movements with audio output to bring puppet characters to life. Traditional animatronic systems require expensive commercial motion controllers and significant programming expertise, making them inaccessible to hobbyists and small-scale creators. The project combines a Linux-based host computer (Raspberry Pi or OrangePi) with a distributed network of ESP32 nodes equipped with W5500 Ethernet controllers to achieve real-time, synchronized control of servos and relays. The primary goal is to enable anyone to create lifelike puppet performances — from a single character to an entire puppet rock band — without writing a single line of code. Instead, movements are recorded live using a joystick synchronized to audio playback, then reproduced on demand during performances.

2. Key Technical Elements and Selection Reasons (Methodology)

Components were selected based on accessibility, cost-efficiency, and scalability for both small and large-scale installations.

Host Controller (Raspberry Pi / OrangePi PC): Selected as the central brain running Linux, capable of processing audio playback and servo coordinate data simultaneously. Its GPIO and I2C interfaces provide direct hardware connectivity, while its network stack enables communication with distributed nodes.

Local Servo Driver (PCA9685): Up to 64 PCA9685 PWM boards can be daisy-chained via I2C, each controlling 16 servo channels. This provides direct, low-latency servo control for installations where the host and servos are physically close.

Network Node (ESP32 with W5500): For installations requiring physical distance or massive scale, ESP32 modules paired with W5500 Ethernet controllers serve as distributed servo/relay drivers. Each node handles 16 output channels (servos, relays, or a mixture). The W5500 hardware TCP/IP stack ensures reliable packet reception without burdening the ESP32's processing resources.

Input Device (Joystick / Gamepad): A standard USB joystick or gamepad serves as the motion capture device. Two-axis input is mapped to servo positions through a normalized coordinate system (0–4096), allowing servo types to be swapped without re-recording movements.

3. In-depth Analysis of Hardware Operating Principles (Hardware Mechanics)

The system operates on a hybrid architecture combining direct I2C servo control with network-distributed nodes.

Audio-Movement Synchronization: The host computer plays an MP3 file while simultaneously reading joystick positions at a configurable refresh rate (default: 50ms / 20Hz). Each joystick sample is timestamped and stored in a .svo file, creating a frame-by-frame movement recording perfectly aligned to the audio.

Sequential Multi-Channel Recording: Since a joystick provides only two axes (X/Y), complex puppet movements are recorded in multiple passes. For example, mouth movements are recorded first in one pass, then eyelid movements in a second pass, and eye direction in a third. The software merges all passes into a single synchronized output file.

Normalized Coordinate System: All joystick inputs and servo outputs are normalized to a 0–4096 range. This abstraction layer means that if a servo is physically replaced with a different model, or if the joystick hardware changes, existing movement recordings remain fully compatible — only the calibration parameters in the configuration file need updating.

Dual Output Path: During playback, the host simultaneously sends movement data through two paths: (1) directly to PCA9685 boards via I2C for locally connected servos, and (2) as UDP broadcast packets over Ethernet to all W5500-equipped network nodes for remotely distributed servos and relays.

4. Communication Interface: The Role and Necessity of W5500 Network Nodes

Network communication is essential for scaling beyond the physical limitations of direct I2C wiring.

W5500 Hardware TCP/IP on ESP32 Nodes: Each ESP32 network node receives movement data through its W5500 Ethernet controller. The W5500 handles all TCP/IP protocol processing in hardware, allowing the ESP32 to focus entirely on servo PWM signal generation and relay switching. This hardware offloading is critical for maintaining precise servo timing at the 50ms refresh interval.

UDP Broadcast Architecture: The host transmits all servo and relay data in a single UDP broadcast packet (up to 1432 bytes) to port 7625. Every node on the network receives the same packet. Each node is pre-configured with its address and channel mapping, so it extracts only the data words relevant to its assigned servos and relays. This broadcast approach eliminates the need for individual addressing and enables approximately 700 servos across 44 nodes or 11,000 relays across 700 nodes within a single 50ms refresh cycle.

Ethernet vs. WiFi Reliability: While ESP32 nodes support both WiFi and Ethernet connectivity, Ethernet via the W5500 is recommended for production installations due to its deterministic latency and immunity to wireless interference. WiFi remains available as a convenient option for prototyping and temporary setups.

Node Configuration Protocol: A dedicated configuration tool (nodeconfig.pl) sends setup commands to nodes over the same network. Each node stores its address, MAC, servo/relay pin mappings, and channel assignments. A "Bas Conf" hardware jumper on each node enables initial address assignment, preventing accidental reconfiguration during operation. All configurations are tracked in a SQLite database for easy management of large installations.

5. Software Implementation and Optimization (Software & Coding)

The software stack is built entirely in Perl 5, running on any Linux distribution with the required modules.

Recording Interface (trackui.pl): A terminal-based curses UI allows the operator to select which servos to bind to joystick axes, define recording time ranges, and monitor movement values in real-time. The interface supports notebook-style tabbed pages, displaying up to 500+ servos in the default window size.

Block Operations: Recorded movement segments can be saved to and loaded from block files, enabling reuse of common sequences (e.g., a laugh gesture or a wave) across multiple audio tracks without re-recording.

Copy and Transform Functions: The software provides powerful movement manipulation: copying servo tracks between channels, time-shifting movements by arbitrary step counts, inverting movement direction, and rotating movements that exceed boundaries. These operations respect configurable start/stop ranges for precise editing.

Playback Engine (live.pl): During performance, this program sequences through MP3/movement pairs triggered by a simple 4-button control panel. Features include automatic looping for unattended installations (such as museum exhibits triggered by light barriers) and configurable behavior for MP3 completion before advancing to the next sequence.

Network Node Firmware: ESP32 nodes run custom firmware that listens for UDP broadcast packets and translates received data words into PWM signals for servos or digital outputs for relays. The firmware distinguishes between operation data and configuration commands based on packet structure.

6. Project Result and Conclusion

This project demonstrates that a professional-grade animatronic control system can be built using open-source software and affordable hardware including W5500-based network nodes.

Technical Achievement: The system supports real-time synchronized control of hundreds of servos and thousands of relays at 20Hz refresh rate. The normalized coordinate system ensures long-term maintainability, as hardware changes never require re-recording of movement data.

Scalability: The W5500 Ethernet-based node architecture allows virtually unlimited expansion. Adding more puppets or characters to an installation requires only adding more ESP32 nodes and connecting them to the existing network — no changes to the host software or existing configurations are needed.

Accessibility: The entire system — from recording to performance — operates without any programming. A puppet creator needs only a joystick, a microphone for audio recording, and the intuitive terminal UI to bring their characters to life.

Conclusion: By combining a Linux host with distributed W5500 network nodes, this project delivers an economical, scalable, and fully open-source animatronic platform capable of professional-quality puppet performances.

1. 프로젝트 배경 및 기술적 목표

이 프로젝트는 애니마트로닉스의 근본적인 과제, 즉 서보 모터의 복잡한 움직임을 오디오 출력과 동기화하여 인형 캐릭터에 생명을 불어넣는 문제를 해결하기 위해 시작되었습니다. 기존의 상용 애니마트로닉 시스템은 고가의 모션 컨트롤러와 상당한 프로그래밍 지식을 필요로 하여, 취미 제작자나 소규모 창작자가 접근하기 어려웠습니다. 이 프로젝트는 리눅스 기반 호스트 컴퓨터(Raspberry Pi 또는 OrangePi)와 W5500 이더넷 컨트롤러가 장착된 ESP32 네트워크 노드의 분산형 구조를 결합하여, 서보 및 릴레이의 실시간 동기 제어를 실현합니다. 핵심 목표는 코드를 한 줄도 작성하지 않고도 누구나 생동감 있는 인형극을 만들 수 있게 하는 것입니다. 움직임은 오디오 재생에 맞춰 조이스틱으로 실시간 녹화하고, 공연 시 그대로 재생하는 방식으로 구현됩니다.

2. 핵심 기술 요소 및 선정 이유 (Methodology)

접근성, 비용 효율성, 확장성을 기준으로 소규모 및 대규모 설치 모두에 적합한 부품을 선정하였습니다.

호스트 컨트롤러 (Raspberry Pi / OrangePi PC): 리눅스를 실행하는 중앙 두뇌로 선정되었으며, 오디오 재생과 서보 좌표 데이터를 동시에 처리할 수 있습니다. GPIO 및 I2C 인터페이스를 통한 직접 하드웨어 연결과 네트워크 스택을 통한 분산 노드 통신이 가능합니다.

로컬 서보 드라이버 (PCA9685): I2C를 통해 최대 64개의 PCA9685 PWM 보드를 데이지 체인으로 연결할 수 있으며, 각 보드는 16개의 서보 채널을 제어합니다. 호스트와 서보가 물리적으로 가까운 설치 환경에서 낮은 지연시간의 직접 제어를 제공합니다.

네트워크 노드 (ESP32 + W5500): 물리적 거리가 필요하거나 대규모 확장이 요구되는 설치에서는 W5500 이더넷 컨트롤러와 결합된 ESP32 모듈이 분산형 서보/릴레이 드라이버로 사용됩니다. 각 노드는 16개의 출력 채널(서보, 릴레이 또는 혼합)을 처리합니다. W5500의 하드웨어 TCP/IP 스택이 ESP32의 처리 자원을 소모하지 않으면서 안정적인 패킷 수신을 보장합니다.

입력 장치 (조이스틱 / 게임패드): 표준 USB 조이스틱 또는 게임패드가 모션 캡처 장치로 사용됩니다. 2축 입력이 정규화된 좌표 시스템(0–4096)을 통해 서보 위치에 매핑되어, 서보 종류를 교체해도 기존 녹화 데이터를 다시 녹화할 필요가 없습니다.

3. 하드웨어 작동 원리에 대한 심층 분석 (Hardware Mechanics)

시스템은 직접 I2C 서보 제어와 네트워크 분산 노드를 결합한 하이브리드 구조로 작동합니다.

오디오-움직임 동기화: 호스트 컴퓨터가 MP3 파일을 재생하는 동시에 설정 가능한 갱신 주기(기본: 50ms / 20Hz)로 조이스틱 위치를 읽어들입니다. 각 조이스틱 샘플에 타임스탬프가 찍혀 .svo 파일에 저장되어, 오디오와 완벽하게 정렬된 프레임 단위 움직임 녹화가 생성됩니다.

순차적 다채널 녹화: 조이스틱은 2축(X/Y)만 제공하므로, 복잡한 인형 움직임은 여러 차례에 걸쳐 녹화됩니다. 예를 들어, 첫 번째 패스에서 입 움직임을, 두 번째 패스에서 눈꺼풀 움직임을, 세 번째 패스에서 눈 방향을 녹화합니다. 소프트웨어가 모든 패스를 하나의 동기화된 출력 파일로 합칩니다.

정규화 좌표 시스템: 모든 조이스틱 입력과 서보 출력은 0–4096 범위로 정규화됩니다. 이 추상화 계층 덕분에 서보를 다른 모델로 물리적으로 교체하거나 조이스틱 하드웨어가 변경되어도, 기존 움직임 녹화는 완전히 호환됩니다 — 설정 파일의 캘리브레이션 파라미터만 업데이트하면 됩니다.

이중 출력 경로: 재생 시 호스트는 동시에 두 경로로 움직임 데이터를 전송합니다: (1) I2C를 통해 로컬 연결된 PCA9685 보드로 직접, (2) 이더넷을 통한 UDP 브로드캐스트 패킷으로 원격 분산된 W5500 장착 네트워크 노드로.

4. 통신 인터페이스: W5500 네트워크 노드의 역할과 필요성

네트워크 통신은 직접 I2C 배선의 물리적 한계를 넘어 확장하기 위해 필수적입니다.

ESP32 노드의 W5500 하드웨어 TCP/IP: 각 ESP32 네트워크 노드는 W5500 이더넷 컨트롤러를 통해 움직임 데이터를 수신합니다. W5500이 모든 TCP/IP 프로토콜 처리를 하드웨어적으로 수행하므로, ESP32는 서보 PWM 신호 생성과 릴레이 스위칭에만 전념할 수 있습니다. 이 하드웨어 오프로딩은 50ms 갱신 주기에서 정확한 서보 타이밍을 유지하는 데 핵심적입니다.

UDP 브로드캐스트 아키텍처: 호스트는 모든 서보 및 릴레이 데이터를 단일 UDP 브로드캐스트 패킷(최대 1432바이트)으로 포트 7625에 전송합니다. 네트워크의 모든 노드가 동일한 패킷을 수신합니다. 각 노드는 자신의 주소와 채널 매핑이 사전 설정되어 있어, 할당된 서보 및 릴레이에 해당하는 데이터 워드만 추출합니다. 이 브로드캐스트 방식은 개별 주소 지정의 필요를 없애고, 단일 50ms 갱신 주기 내에서 약 700개의 서보(44개 노드) 또는 **약 11,000개의 릴레이(700개 노드)**를 제어할 수 있게 합니다.

이더넷 vs. WiFi 안정성: ESP32 노드는 WiFi와 이더넷 연결을 모두 지원하지만, W5500을 통한 이더넷이 결정적 지연시간과 무선 간섭 면역성 덕분에 실제 운영 환경에서 권장됩니다. WiFi는 프로토타이핑과 임시 설치에 편리한 옵션으로 남아 있습니다.

노드 설정 프로토콜: 전용 설정 도구(nodeconfig.pl)가 동일한 네트워크를 통해 노드에 설정 명령을 전송합니다. 각 노드는 주소, MAC, 서보/릴레이 핀 매핑, 채널 할당을 저장합니다. 각 노드의 "Bas Conf" 하드웨어 점퍼가 초기 주소 할당을 활성화하여 운영 중 실수로 재설정되는 것을 방지합니다. 모든 설정은 SQLite 데이터베이스에서 추적되어 대규모 설치의 관리를 용이하게 합니다.

5. 소프트웨어 구현 및 최적화 (Software & Coding)

소프트웨어 스택은 필요한 모듈을 갖춘 모든 리눅스 배포판에서 실행되는 Perl 5로 전체 구축되었습니다.

녹화 인터페이스 (trackui.pl): 터미널 기반 curses UI를 통해 운영자가 어떤 서보를 조이스틱 축에 바인딩할지 선택하고, 녹화 시간 범위를 정의하며, 실시간으로 움직임 값을 모니터링할 수 있습니다. 인터페이스는 노트북 스타일의 탭 페이지를 지원하여 기본 창 크기에서 500개 이상의 서보를 표시할 수 있습니다.

블록 오퍼레이션: 녹화된 움직임 세그먼트를 블록 파일로 저장하고 불러올 수 있어, 공통 시퀀스(예: 웃음 동작, 손 흔들기)를 여러 오디오 트랙에서 재녹화 없이 재사용할 수 있습니다.

복사 및 변환 기능: 채널 간 서보 트랙 복사, 임의 스텝 수만큼의 시간 이동, 움직임 방향 반전, 경계 초과 시 회전 등의 강력한 움직임 조작 기능을 제공합니다. 이러한 연산은 설정 가능한 시작/정지 범위를 존중하여 정밀한 편집이 가능합니다.

재생 엔진 (live.pl): 공연 시 이 프로그램이 간단한 4버튼 컨트롤 패널로 트리거되는 MP3/움직임 쌍을 순차 재생합니다. 무인 설치(예: 광센서로 트리거되는 박물관 전시)를 위한 자동 루프 기능과, 다음 시퀀스로 넘어가기 전 MP3 완전 재생 설정 등의 기능이 포함되어 있습니다.

네트워크 노드 펌웨어: ESP32 노드는 UDP 브로드캐스트 패킷을 수신하고 수신된 데이터 워드를 서보용 PWM 신호 또는 릴레이용 디지털 출력으로 변환하는 커스텀 펌웨어를 실행합니다. 펌웨어는 패킷 구조에 따라 운영 데이터와 설정 명령을 구분합니다.

6. 프로젝트 결과 및 결론

이 프로젝트는 오픈소스 소프트웨어와 W5500 기반 네트워크 노드를 포함한 저렴한 하드웨어만으로 전문가 수준의 애니마트로닉 제어 시스템을 구축할 수 있음을 증명합니다.

기술적 성과: 20Hz 갱신 주기에서 수백 개의 서보와 수천 개의 릴레이를 실시간 동기 제어할 수 있습니다. 정규화 좌표 시스템은 하드웨어 변경 시에도 움직임 데이터 재녹화가 불필요하여 장기적 유지보수성을 보장합니다.

확장성: W5500 이더넷 기반 노드 아키텍처는 사실상 무제한적 확장을 가능하게 합니다. 설치에 더 많은 인형이나 캐릭터를 추가하려면 ESP32 노드를 추가하고 기존 네트워크에 연결하기만 하면 됩니다 — 호스트 소프트웨어나 기존 설정의 변경이 필요 없습니다.

접근성: 녹화부터 공연까지 전체 시스템이 프로그래밍 없이 작동합니다. 인형 창작자에게 필요한 것은 조이스틱, 오디오 녹음용 마이크, 그리고 직관적인 터미널 UI뿐입니다.

결론: 리눅스 호스트와 분산형 W5500 네트워크 노드를 결합하여, 전문 품질의 인형극 공연이 가능한 경제적이고 확장 가능한 완전 오픈소스 애니마트로닉 플랫폼을 완성하였습니다.