Broadcast Camera Tracking Gateway: STM32F401 and W5500 Free-D Tracking Box

https://github.com/abelalves962-oss/broadcast-camera-tracking-gateway

This introduction is based on the original repository as of 2026-10-06 (the date of its latest push). The repository publishes no release version.

Overview

Broadcast Camera Tracking Gateway is an embedded gateway that turns camera and lens tracking data into Free-D packets that broadcast systems can use. A Tracking Box built on an STM32F401 Cortex-M4 MCU receives serial / RS-485 data, decodes and normalizes it, applies configurable processing and calibration, encodes Free-D packets, and sends them over Ethernet through a WIZnet W5500 controller. A companion C# / .NET 8 WPF application, the Tracking Monitor, handles configuration, telemetry and diagnostics.

The author describes the repository as a sanitized, laboratory-tested functional prototype published as an engineering portfolio project. It is explicitly not presented as a turnkey commercial or safety-critical product. The README sets out the engineering concerns the system addresses: reliable serial and RS-485 acquisition, decoding of camera and lens tracking packets, coordinate transformation and calibration, deterministic processing on embedded hardware, Free-D packet generation, "Ethernet transport through a dedicated controller", persistent configuration, and recovery logic with health monitoring across the serial, synchronization, network and application layers.

Additional photos are available in the original repository: https://github.com/abelalves962-oss/broadcast-camera-tracking-gateway

Hardware & Software Configuration

The system has two halves. Real-time acquisition and protocol conversion stay in the embedded Tracking Box, while visualization and engineering controls stay in the desktop Monitor. The README states the stack as follows.

According to the README, the firmware's high-level structure covers peripheral initialization, serial reception, tracking packet decoding, coordinate processing, synthetic calibration maps, Free-D encoding, W5500 Ethernet transport, emulated EEPROM configuration, watchdog handling and runtime diagnostics. The repository tree separates firmware/ (sanitized embedded source), monitor/ (the WPF monitor and its automated tests), docs/ (architecture and security documentation) and config-examples/ (synthetic, documentation-only calibration).

The WPF Monitor shows Tracking Box online/offline status, Ethernet link and application-connection status, serial RX activity and errors, synchronization/reference monitoring, Free-D transmission status, telemetry counters and rate graphs, health indicators and event history. Configuration and diagnostic operations are protected by password-based local authorization, and no default or operational credential ships with the code.

The README is clear about what this public snapshot does and does not contain. Vendor HAL, CMSIS, WIZnet and middleware sources are not redistributed. Because those dependencies were left out on purpose, the public firmware snapshot was not compiled as part of the sanitization process. Reproducible public firmware build instructions are listed on the roadmap rather than provided. Network defaults use RFC 5737 documentation-only addresses, and installation-specific dimensions, offsets, coordinates and calibration tables were replaced with clearly synthetic examples. The project carries no open-source license: the README states "All rights reserved" and reserves commercial use and redistribution for prior authorization from the author.

System Architecture

The README gives the primary tracking path as Camera / Lens → Serial / RS-485 → STM32 Tracking Box → Tracking Decoder → Data Processing / Calibration → Free-D Encoder → Ethernet → Tracking Destination. A separate supervisory path connects the Tracking Monitor to the Tracking Box for configuration and diagnostics.

flowchart LR
  CAM["Camera / Lens"] -->|Serial / RS-485| DEC
  subgraph BOX["STM32F401 Tracking Box"]
    DEC["Tracking Decoder"] --> PROC["Processing /<br/>Calibration"]
    PROC --> ENC["Free-D Encoder"]
    CFG["Emulated EEPROM<br/>configuration"] -.-> PROC
  end
  ENC -->|SPI| W5500["WIZnet W5500"]
  W5500 -->|Ethernet| DEST["Tracking Destination"]
  MON["Tracking Monitor<br/>C# / .NET 8 WPF"] <-->|Config / diagnostics| BOX

Keeping the hard real-time work on the MCU and the visual tooling on the desktop means the conversion path does not depend on the Monitor running. The Monitor only observes and configures. Its automated tests, which the README reports as passing, use loopback networking, synthetic protocol payloads and temporary authentication data. They cover authentication hashing and salt handling, connection recovery and online/offline transitions, telemetry and configuration parsing, TCP timing and diagnostic classification, synthetic network configuration, Free-D destination parsing, axis inversions and offsets, and polling concurrency and retry behavior.

Role of the WIZnet W5500

The W5500 is the Ethernet interface of the Tracking Box. It is the last hop of the tracking path, where the Free-D packets produced by the STM32F401 leave the box over Ethernet toward the tracking destination. The README lists "an Ethernet interface using a W5500 controller" among the prototype's components and "W5500 Ethernet transport" in the firmware structure. The source files show how the chip is brought up.

In firmware/Core/Src/main.c#L38 the firmware includes w5500_spi.h, the SPI driver layer for the chip. At main.c#L148 a PinCtlW5500 structure assigns the chip-select line to SOFT_CS_ETH_GPIO_Port, a GPIO-driven (software) chip select on the STM32. At main.c#L330 W5500_STM32_begin(configRede) applies the network parameters; the comment on the preceding line reads "Configura os parametros de rede do w5500" (configures the W5500 network parameters).

The socket side lives in the configuration module. firmware/LibsCam4/config.h#L20 includes w5500_spi.h, and the next line pulls in wizchip_conf from the WIZnet ioLibrary. In firmware/LibsCam4/config.c#L398 the firmware calls W5500_STM32_TCP_begin(PORTA, socketNumber, MODO_TCP_UNI_BROAD) to open a TCP socket on the chip. The comment that follows notes that socket() leaves the W5500 in the INIT state and that LISTEN is opened in the same cycle. The socket state machine therefore runs inside the W5500's own socket registers, driven from the MCU over SPI. The repository's THIRD_PARTY_NOTICES.md also names "WIZnet ioLibrary and W5500 Ethernet controller support" as an external dependency, and docs/architecture.md labels the network block "Ethernet (W5500)".

Put together, the data flow is: tracking packets arrive on the serial / RS-485 input, the STM32F401 decodes, calibrates and Free-D-encodes them, and the encoded output is handed over SPI to the W5500, whose TCP/IP sockets carry it onto the Ethernet link. The Monitor reports the resulting Ethernet link, application-connection and Free-D transmission status. One caveat: the WIZnet ioLibrary sources themselves are not redistributed in this snapshot, so the firmware cannot be built as published without adding them.

FAQ

What does the gateway output? Free-D tracking packets, generated on the STM32F401 by a Free-D encoder and sent over Ethernet to a tracking destination.

Which MCU and Ethernet controller does it use? An STM32F401 Cortex-M4 MCU with a WIZnet W5500 Ethernet controller attached through the w5500_spi.h driver layer.

Can I build the firmware straight from the repository? Not as published. Vendor HAL, CMSIS, WIZnet and middleware sources were deliberately excluded, the public firmware snapshot was not compiled during sanitization, and reproducible build instructions are still on the roadmap.

Are the network addresses and calibration values real? No. Displayed IP addresses belong to RFC 5737 documentation ranges, and calibration values and maps are synthetic.

Can I reuse the code? No open-source license is granted. The README reserves all rights and requires prior authorization from the author for commercial use or redistribution.

About the Author

The project is by Paulo Abel Pereira Alves (GitHub: abelalves962-oss), who describes his fields as Telecommunications Engineering, Broadcast Engineering, Embedded Systems and Python / AI. He publishes the repository in English and Portuguese as a portfolio of work that combines embedded firmware, broadcast camera tracking and desktop diagnostics tooling.

개요

Broadcast Camera Tracking Gateway는 카메라·렌즈 트래킹 데이터를 방송 시스템이 쓸 수 있는 Free-D 패킷으로 바꿔 주는 임베디드 게이트웨이다. STM32F401 Cortex-M4 MCU 기반의 Tracking Box가 시리얼 / RS-485 데이터를 받아 디코딩·정규화하고, 설정 가능한 처리와 캘리브레이션을 적용한 뒤 Free-D 패킷으로 인코딩해 WIZnet W5500 컨트롤러를 거쳐 이더넷으로 내보낸다. 함께 제공되는 C# / .NET 8 WPF 데스크톱 앱 Tracking Monitor가 설정·텔레메트리·진단을 맡는다.

이 소개는 2026-10-06(마지막 push 날짜) 시점의 원본 저장소를 기준으로 한다. 저장소에는 릴리스 버전이 없다.

저자는 이 저장소를 엔지니어링 포트폴리오로 공개한, 공개용으로 정리(sanitize)된 실험실 검증 기능 프로토타입이라고 소개한다. 턴키 상용 제품이나 안전 필수(safety-critical) 제품이 아니라는 점도 분명히 밝힌다. README가 꼽는 공학적 과제는 신뢰할 수 있는 시리얼·RS-485 수집, 카메라·렌즈 트래킹 패킷 디코딩, 좌표 변환과 캘리브레이션, 임베디드 하드웨어에서의 결정적 처리, Free-D 패킷 생성, "전용 컨트롤러를 통한 이더넷 전송", 설정 영구 저장, 그리고 시리얼·동기·네트워크·애플리케이션 계층 전반의 복구 로직과 상태 감시다.

추가 사진은 원본 저장소에서 볼 수 있다: https://github.com/abelalves962-oss/broadcast-camera-tracking-gateway

하드웨어·소프트웨어 구성

시스템은 두 부분으로 나뉜다. 실시간 수집과 프로토콜 변환은 임베디드 Tracking Box가 맡고, 시각화와 엔지니어링 제어는 데스크톱 Monitor가 맡는다. README에 적힌 구성은 다음과 같다.

README에 따르면 펌웨어의 상위 구조는 주변장치 초기화, 시리얼 수신, 트래킹 패킷 디코딩, 좌표 처리, 합성(synthetic) 캘리브레이션 맵, Free-D 인코딩, W5500 이더넷 전송, 에뮬레이션 EEPROM 설정, 워치독 처리, 런타임 진단으로 이뤄진다. 저장소는 firmware/(정리된 임베디드 소스), monitor/(WPF 모니터와 자동 테스트), docs/(구조·보안 문서), config-examples/(문서용 합성 캘리브레이션)로 나뉜다.

WPF Monitor는 Tracking Box의 온라인/오프라인 상태, 이더넷 링크와 애플리케이션 연결 상태, 시리얼 RX 활동과 오류, 동기/레퍼런스 감시, Free-D 송신 상태, 텔레메트리 카운터와 전송률 그래프, 상태 지표와 이벤트 이력을 보여 준다. 설정·진단 작업은 비밀번호 기반 로컬 인증으로 보호되며, 기본 자격증명이나 운영용 자격증명은 포함돼 있지 않다.

README는 이 공개 스냅숏에 무엇이 있고 무엇이 없는지를 분명히 밝힌다. 벤더 HAL, CMSIS, WIZnet, 미들웨어 소스는 재배포하지 않는다. 그 의존성을 의도적으로 뺐기 때문에 공개 펌웨어 스냅숏은 정리 과정에서 컴파일되지 않았다. 재현 가능한 공개 펌웨어 빌드 절차는 제공되지 않고 로드맵에 올라 있다. 네트워크 기본값은 RFC 5737 문서 전용 주소를 쓰고, 설치 현장 고유의 치수·오프셋·좌표·캘리브레이션 표는 명백한 합성 예시로 바뀌었다. 오픈소스 라이선스는 없다. README는 "All rights reserved"를 명시하고, 상업적 사용과 재배포에는 저자의 사전 승인이 필요하다고 적는다.

시스템 구조

README가 제시하는 주 트래킹 경로는 Camera / Lens → Serial / RS-485 → STM32 Tracking Box → Tracking Decoder → Data Processing / Calibration → Free-D Encoder → Ethernet → Tracking Destination이다. 이와 별도로 Tracking Monitor가 설정·진단을 위해 Tracking Box와 양방향으로 연결되는 감독 경로가 있다.

실시간 처리는 MCU에, 시각화 도구는 데스크톱에 둔 덕분에 변환 경로는 Monitor가 켜져 있는지와 상관없이 동작한다. Monitor는 관찰하고 설정할 뿐이다. README가 통과했다고 보고하는 Monitor 자동 테스트는 loopback 네트워킹, 합성 프로토콜 페이로드, 임시 인증 데이터를 사용한다. 검증 범위는 인증 해시와 salt 처리, 연결 복구와 온라인/오프라인 전이, 텔레메트리·설정 파싱, TCP 타이밍과 진단 분류, 합성 네트워크 설정, Free-D 목적지 파싱, 축 반전과 오프셋, 폴링 동시성과 재시도 동작이다.

WIZnet W5500의 역할

W5500은 Tracking Box의 이더넷 인터페이스다. 트래킹 경로의 마지막 구간을 맡아, STM32F401이 만든 Free-D 패킷을 이더넷으로 트래킹 목적지까지 내보낸다. README는 프로토타입 구성 요소로 "an Ethernet interface using a W5500 controller"를, 펌웨어 구조로 "W5500 Ethernet transport"를 적는다. 칩을 실제로 올리는 방식은 소스 파일에서 확인된다.

firmware/Core/Src/main.c#L38에서 펌웨어는 칩의 SPI 드라이버 계층인 w5500_spi.h를 포함한다. main.c#L148의 PinCtlW5500 구조체는 칩 선택 신호를 SOFT_CS_ETH_GPIO_Port에 할당한다. STM32의 GPIO로 구동하는 소프트웨어 칩 선택이다. main.c#L330의 W5500_STM32_begin(configRede)가 네트워크 파라미터를 적용하며, 바로 앞 줄 주석은 "Configura os parametros de rede do w5500"(W5500 네트워크 파라미터 설정)이다.

소켓 쪽은 설정 모듈에 있다. firmware/LibsCam4/config.h#L20이 w5500_spi.h를 포함하고, 다음 줄에서 WIZnet ioLibrary의 wizchip_conf를 불러온다. firmware/LibsCam4/config.c#L398에서는 W5500_STM32_TCP_begin(PORTA, socketNumber, MODO_TCP_UNI_BROAD)를 호출해 칩에 TCP 소켓을 연다. 이어지는 주석은 socket()이 W5500을 INIT 상태로 두며 LISTEN도 같은 사이클에서 연다고 설명한다. 즉 소켓 상태 머신은 W5500 자체의 소켓 레지스터 안에서 돌아가고, MCU는 SPI로 이를 구동한다. 저장소의 THIRD_PARTY_NOTICES.md도 외부 의존성으로 "WIZnet ioLibrary and W5500 Ethernet controller support"를 명시하며, docs/architecture.md는 네트워크 블록을 "Ethernet (W5500)"로 표시한다.

정리하면 데이터 흐름은 이렇다. 트래킹 패킷이 시리얼 / RS-485 입력으로 들어오면, STM32F401이 이를 디코딩·캘리브레이션해 Free-D로 인코딩하고, 인코딩된 출력을 SPI로 W5500에 넘긴다. W5500의 TCP/IP 소켓이 그 데이터를 이더넷 링크로 실어 보낸다. 그 결과로 생기는 이더넷 링크, 애플리케이션 연결, Free-D 송신 상태는 Monitor가 보여 준다. 다만 이 스냅숏에는 WIZnet ioLibrary 소스 자체가 재배포돼 있지 않으므로, 공개된 상태 그대로는 그 소스를 추가하지 않으면 펌웨어를 빌드할 수 없다.

자주 묻는 질문

게이트웨이는 무엇을 출력하나? Free-D 트래킹 패킷이다. STM32F401의 Free-D 인코더가 만들고 이더넷으로 트래킹 목적지에 보낸다.

어떤 MCU와 이더넷 컨트롤러를 쓰나? STM32F401 Cortex-M4 MCU에 WIZnet W5500 이더넷 컨트롤러를 w5500_spi.h 드라이버 계층으로 연결한다.

저장소만으로 펌웨어를 빌드할 수 있나? 공개된 상태로는 안 된다. 벤더 HAL, CMSIS, WIZnet, 미들웨어 소스가 의도적으로 빠졌고, 공개 펌웨어 스냅숏은 정리 과정에서 컴파일되지 않았으며, 재현 가능한 빌드 절차는 아직 로드맵에 있다.

네트워크 주소와 캘리브레이션 값은 실제 값인가? 아니다. 표시된 IP 주소는 RFC 5737 문서용 대역이고, 캘리브레이션 값과 맵은 합성 값이다.

코드를 재사용해도 되나? 오픈소스 라이선스는 부여되지 않는다. README는 모든 권리를 유보하며, 상업적 사용이나 재배포에는 저자의 사전 승인이 필요하다고 밝힌다.

저자 소개

이 프로젝트의 저자는 Paulo Abel Pereira Alves(GitHub: abelalves962-oss)다. 그는 자신의 분야를 Telecommunications Engineering, Broadcast Engineering, Embedded Systems, Python / AI로 소개한다. 임베디드 펌웨어, 방송용 카메라 트래킹, 데스크톱 진단 도구를 한데 묶은 포트폴리오로 이 저장소를 영어와 포르투갈어로 공개했다.