skywalker-1/README.md

<div align="center">

# SkyWalker-1

**Reverse-engineered documentation, custom firmware, and Python tooling for the Genpix SkyWalker-1 DVB-S USB 2.0 satellite receiver.**

[![Docs](https://img.shields.io/badge/docs-skywalker--1.warehack.ing-0a7e8c?style=flat-square)](https://skywalker-1.warehack.ing)
[![Firmware](https://img.shields.io/badge/firmware-SDCC%20%2B%20fx2lib-1a1a2e?style=flat-square)](https://skywalker-1.warehack.ing/firmware/custom-v301/)
[![License](https://img.shields.io/badge/license-open--source-3d5a80?style=flat-square)](#license)

</div>

---

The SkyWalker-1 is a standalone USB 2.0 DVB-S receiver built around a **Cypress FX2LP** (CY7C68013A) microcontroller and **Broadcom BCM4500** satellite demodulator. It was designed by [Genpix Electronics](https://www.genpix-electronics.com/index.php?act=viewDoc&docId=9) for DVB-S, Turbo-coded, Digicipher II, and DSS reception.

This project documents the device's complete internal architecture -- every vendor command, register, GPIO pin, and data path -- built up from Linux kernel driver analysis, Ghidra firmware disassembly of five firmware images, Windows BDA driver source review, and original custom firmware development.

**[Browse the full documentation at skywalker-1.warehack.ing](https://skywalker-1.warehack.ing)**

## What's Here

```
skywalker-1/
  firmware/           Custom FX2 firmware (SDCC + fx2lib, 1441 lines of C)
    skywalker1.c        Full replacement firmware with 10 custom vendor commands
    Makefile            Build rules targeting CY7C68013A
    dscr.a51            USB descriptors (VID 0x09C0, PID 0x0203)
  firmware-dump/      Extracted stock firmware binaries (v2.06, v2.10, v2.13 x3)
  firmware-driver/    Genpix Windows BDA driver source (reference material)
  tools/              Python utilities for direct hardware interaction
    skywalker.py        Multi-mode RF tool: spectrum, scan, monitor, lband, track
    skywalker_lib.py    Shared library: USB transport, BCM4500 register access
    fw_load.py          FX2 RAM firmware loader via 0xA0 vendor request
    tune.py             Transponder tuner with lock detection and BER readout
    ts_analyze.py       MPEG-2 transport stream parser and PID analyzer
    eeprom_dump.py      Full EEPROM image extraction
    eeprom_write.py     EEPROM flash tool with C2 format support
    wine_memdump.py     Extract firmware from Genpix Windows updater EXEs
    test_*.py           Boot sequence and I2C debug/isolation harnesses
  site/               Astro Starlight documentation (37 pages, 9 sections)
  docs/               Raw analysis documents and master hardware reference
```

## Hardware at a Glance

| | |
|---|---|
| **MCU** | Cypress CY7C68013A (FX2LP) -- 8051 core at 48 MHz, USB 2.0 Hi-Speed |
| **Demodulator** | Broadcom BCM4500 -- DVB-S / Turbo / DCII / DSS, 128-pin MQFP |
| **IF Range** | 950 -- 2150 MHz |
| **Symbol Rate** | 256 Ksps -- 30 Msps |
| **LNB Control** | 13/18V, 22 kHz tone, DiSEqC 1.0/1.2, legacy switches |
| **Connector** | IEC F-type female |
| **Transport** | 8-bit parallel bus via GPIF into USB bulk endpoint EP2 |

```
                      +--[ I2C EEPROM 0x51 ]
                      |
USB 2.0 HS           |    I2C Bus (400 kHz)
Host PC  <----> [ CY7C68013A FX2LP ] <-----> [ BCM4500 Demod 0x08 ]
                  |  8051 @ 48 MHz  |            |
                  |  GPIF Engine    |<-----------+  8-bit parallel TS
                  |  EP2 Bulk IN    |
                  |  GPIO (P0/P3)   |---> [ 22 kHz Osc ] ---> LNB/Coax
                  |                 |---> [ LNB Voltage Ctrl ]
                  +-----------------+
                      |
                      +--[ Tuner/LNB IC 0x10 ]
```

**Supported modulations:** DVB-S (QPSK), DVB-S (BPSK), Turbo QPSK, Turbo 8PSK, Turbo 16QAM, Digicipher II (Combo, Split I/Q, Offset QPSK), DSS (QPSK).

> DVB-S2 is **not supported**. The BCM4500 predates DVB-S2 and contains no LDPC or BCH decoder hardware. This is a silicon limitation -- no firmware update can change it. See the [DVB-S2 investigation](https://skywalker-1.warehack.ing/driver/dvb-s2/).

## Custom Firmware

The stock EEPROM firmware was replaced with an open-source implementation built from scratch using **SDCC** and **fx2lib**. It implements all stock vendor commands (kernel driver compatible) plus 10 new diagnostic and analysis commands:

| Command | ID | Purpose |
|---------|-----|---------|
| Spectrum Sweep | `0xB0` | AGC-based power sweep across IF range |
| Raw Demod Read | `0xB1` | Direct BCM4500 indirect register read |
| Raw Demod Write | `0xB2` | Direct BCM4500 indirect register write |
| Blind Scan | `0xB3` | Carrier detection at arbitrary frequency |
| Signal Monitor | `0xB7` | Combined SNR + AGC + lock in single transfer |
| Tune Monitor | `0xB8` | Tune + dwell + measure in one round-trip |
| Multi Reg Read | `0xB9` | Batch read of contiguous indirect registers |

Build and load:

```bash
cd firmware
make                          # requires SDCC + fx2lib
make load                     # RAM-loads via fw_load.py (does not touch EEPROM)
```

## Python Tools

All tools communicate directly with the SkyWalker-1 over USB using `pyusb`. No kernel driver required.

```bash
# Load custom firmware into FX2 RAM
python tools/fw_load.py firmware/build/skywalker1.bix

# Tune to a transponder and check lock
python tools/tune.py --freq 12224 --sr 20000 --pol H --mod dvb-s

# Sweep the IF band and render ASCII spectrum
python tools/skywalker.py spectrum --start 950 --stop 2150 --step 5

# Real-time signal strength (dish alignment)
python tools/skywalker.py monitor --freq 1175

# Dump full EEPROM contents
python tools/eeprom_dump.py --output eeprom.bin
```

The `skywalker.py` multi-mode tool provides five operating modes: `spectrum` (sweep analyzer), `scan` (transponder finder), `monitor` (signal strength meter), `lband` (direct L-band input), and `track` (carrier/beacon tracker with CSV logging).

## Documentation Site

The full documentation is published at **[skywalker-1.warehack.ing](https://skywalker-1.warehack.ing)** and covers:

| Section | Pages | Covers |
|---------|-------|--------|
| **Hardware** | 4 | Board architecture, GPIO pin map, RF specifications |
| **USB Interface** | 4 | 30 vendor commands, boot sequence, endpoint layout |
| **BCM4500** | 5 | Register map, indirect access protocol, tuning sequence, GPIF streaming, signal monitoring |
| **LNB & DiSEqC** | 3 | Voltage/tone control, DiSEqC 1.0/1.2, legacy Dish switches |
| **I2C Bus** | 2 | Bus architecture, STOP corruption bug root cause analysis |
| **Firmware** | 7 | 5 stock versions compared, custom v3.01 and v3.02, storage formats |
| **Driver** | 2 | Linux gp8psk kernel driver, DVB-S2 incompatibility investigation |
| **Tools** | 7 | Every Python utility documented with usage examples |
| **Reference** | 1 | Consolidated master reference (registers, commands, GPIO, I2C) |

To run the docs site locally:

```bash
cd site
npm install
npm run dev        # http://localhost:4321
```

<details>
<summary>Docker deployment</summary>

The docs site includes a multi-stage Dockerfile with dev and prod targets. Production serves static files through Caddy.

```bash
cd site

# Development (HMR via volume mounts)
APP_ENV=dev docker compose up --build

# Production (static build served by Caddy)
APP_ENV=prod docker compose up --build -d
```

</details>

## Project History

This project started with USB packet captures and `lsusb` output, then progressed through increasingly deep layers of the hardware:

1. **EEPROM extraction** -- dumped raw firmware bytes over I2C
2. **Ghidra disassembly** -- decompiled five 8051 firmware images, mapped all functions and vendor commands
3. **Windows driver analysis** -- cross-referenced Ghidra findings against Genpix BDA driver source
4. **Linux driver analysis** -- mapped kernel `gp8psk` driver to decoded vendor commands
5. **Custom firmware** -- wrote a full replacement in C, discovered and fixed the [I2C STOP corruption bug](https://skywalker-1.warehack.ing/i2c/stop-corruption-bug/)
6. **RF tooling** -- built spectrum analyzer, blind scanner, and signal monitor on top of the custom command set

## Contributing

This is a niche reverse-engineering project for a specific piece of satellite hardware. If you have a SkyWalker-1 (or other Genpix device using the BCM4500), contributions are welcome -- particularly additional firmware dumps, register documentation, or corrections to the analysis.

## License

The custom firmware source, Python tools, and documentation are open source. Stock firmware binaries in `firmware-dump/` are proprietary Genpix Electronics images retained for research and interoperability purposes.
Normalize line endings to LF across entire repository Apply .gitattributes normalization to convert all CRLF line endings inherited from Windows-origin source files to Unix LF. 175 files, zero content changes. 2026-02-20 10:55:50 -07:00			`<div align="center">`

			`# SkyWalker-1`

			`Reverse-engineered documentation, custom firmware, and Python tooling for the Genpix SkyWalker-1 DVB-S USB 2.0 satellite receiver.`

			`[![Docs](https://img.shields.io/badge/docs-skywalker--1.warehack.ing-0a7e8c?style=flat-square)](https://skywalker-1.warehack.ing)`
			`[![Firmware](https://img.shields.io/badge/firmware-SDCC%20%2B%20fx2lib-1a1a2e?style=flat-square)](https://skywalker-1.warehack.ing/firmware/custom-v301/)`
			`[![License](https://img.shields.io/badge/license-open--source-3d5a80?style=flat-square)](#license)`

			`</div>`

			`---`

			`The SkyWalker-1 is a standalone USB 2.0 DVB-S receiver built around a Cypress FX2LP (CY7C68013A) microcontroller and Broadcom BCM4500 satellite demodulator. It was designed by [Genpix Electronics](https://www.genpix-electronics.com/index.php?act=viewDoc&docId=9) for DVB-S, Turbo-coded, Digicipher II, and DSS reception.`

			`This project documents the device's complete internal architecture -- every vendor command, register, GPIO pin, and data path -- built up from Linux kernel driver analysis, Ghidra firmware disassembly of five firmware images, Windows BDA driver source review, and original custom firmware development.`

			`[Browse the full documentation at skywalker-1.warehack.ing](https://skywalker-1.warehack.ing)`

			`## What's Here`

			```
			`skywalker-1/`
			`firmware/ Custom FX2 firmware (SDCC + fx2lib, 1441 lines of C)`
			`skywalker1.c Full replacement firmware with 10 custom vendor commands`
			`Makefile Build rules targeting CY7C68013A`
			`dscr.a51 USB descriptors (VID 0x09C0, PID 0x0203)`
			`firmware-dump/ Extracted stock firmware binaries (v2.06, v2.10, v2.13 x3)`
			`firmware-driver/ Genpix Windows BDA driver source (reference material)`
			`tools/ Python utilities for direct hardware interaction`
			`skywalker.py Multi-mode RF tool: spectrum, scan, monitor, lband, track`
			`skywalker_lib.py Shared library: USB transport, BCM4500 register access`
			`fw_load.py FX2 RAM firmware loader via 0xA0 vendor request`
			`tune.py Transponder tuner with lock detection and BER readout`
			`ts_analyze.py MPEG-2 transport stream parser and PID analyzer`
			`eeprom_dump.py Full EEPROM image extraction`
			`eeprom_write.py EEPROM flash tool with C2 format support`
			`wine_memdump.py Extract firmware from Genpix Windows updater EXEs`
			`test_*.py Boot sequence and I2C debug/isolation harnesses`
			`site/ Astro Starlight documentation (37 pages, 9 sections)`
			`docs/ Raw analysis documents and master hardware reference`
			```

			`## Hardware at a Glance`

			`\| \| \|`
			`\|---\|---\|`
			`\| MCU \| Cypress CY7C68013A (FX2LP) -- 8051 core at 48 MHz, USB 2.0 Hi-Speed \|`
			`\| Demodulator \| Broadcom BCM4500 -- DVB-S / Turbo / DCII / DSS, 128-pin MQFP \|`
			`\| IF Range \| 950 -- 2150 MHz \|`
			`\| Symbol Rate \| 256 Ksps -- 30 Msps \|`
			`\| LNB Control \| 13/18V, 22 kHz tone, DiSEqC 1.0/1.2, legacy switches \|`
			`\| Connector \| IEC F-type female \|`
			`\| Transport \| 8-bit parallel bus via GPIF into USB bulk endpoint EP2 \|`

			```
			`+--[ I2C EEPROM 0x51 ]`
			`\|`
			`USB 2.0 HS \| I2C Bus (400 kHz)`
			`Host PC <----> [ CY7C68013A FX2LP ] <-----> [ BCM4500 Demod 0x08 ]`
			`\| 8051 @ 48 MHz \| \|`
			`\| GPIF Engine \|<-----------+ 8-bit parallel TS`
			`\| EP2 Bulk IN \|`
			`\| GPIO (P0/P3) \|---> [ 22 kHz Osc ] ---> LNB/Coax`
			`\| \|---> [ LNB Voltage Ctrl ]`
			`+-----------------+`
			`\|`
			`+--[ Tuner/LNB IC 0x10 ]`
			```

			`Supported modulations: DVB-S (QPSK), DVB-S (BPSK), Turbo QPSK, Turbo 8PSK, Turbo 16QAM, Digicipher II (Combo, Split I/Q, Offset QPSK), DSS (QPSK).`

			`> DVB-S2 is not supported. The BCM4500 predates DVB-S2 and contains no LDPC or BCH decoder hardware. This is a silicon limitation -- no firmware update can change it. See the [DVB-S2 investigation](https://skywalker-1.warehack.ing/driver/dvb-s2/).`

			`## Custom Firmware`

			`The stock EEPROM firmware was replaced with an open-source implementation built from scratch using SDCC and fx2lib. It implements all stock vendor commands (kernel driver compatible) plus 10 new diagnostic and analysis commands:`

			`\| Command \| ID \| Purpose \|`
			`\|---------\|-----\|---------\|`
			\| Spectrum Sweep \| `0xB0` \| AGC-based power sweep across IF range \|
			\| Raw Demod Read \| `0xB1` \| Direct BCM4500 indirect register read \|
			\| Raw Demod Write \| `0xB2` \| Direct BCM4500 indirect register write \|
			\| Blind Scan \| `0xB3` \| Carrier detection at arbitrary frequency \|
			\| Signal Monitor \| `0xB7` \| Combined SNR + AGC + lock in single transfer \|
			\| Tune Monitor \| `0xB8` \| Tune + dwell + measure in one round-trip \|
			\| Multi Reg Read \| `0xB9` \| Batch read of contiguous indirect registers \|

			`Build and load:`

			```bash
			`cd firmware`
			`make # requires SDCC + fx2lib`
			`make load # RAM-loads via fw_load.py (does not touch EEPROM)`
			```

			`## Python Tools`

			All tools communicate directly with the SkyWalker-1 over USB using `pyusb`. No kernel driver required.

			```bash
			`# Load custom firmware into FX2 RAM`
			`python tools/fw_load.py firmware/build/skywalker1.bix`

			`# Tune to a transponder and check lock`
			`python tools/tune.py --freq 12224 --sr 20000 --pol H --mod dvb-s`

			`# Sweep the IF band and render ASCII spectrum`
			`python tools/skywalker.py spectrum --start 950 --stop 2150 --step 5`

			`# Real-time signal strength (dish alignment)`
			`python tools/skywalker.py monitor --freq 1175`

			`# Dump full EEPROM contents`
			`python tools/eeprom_dump.py --output eeprom.bin`
			```

			The `skywalker.py` multi-mode tool provides five operating modes: `spectrum` (sweep analyzer), `scan` (transponder finder), `monitor` (signal strength meter), `lband` (direct L-band input), and `track` (carrier/beacon tracker with CSV logging).

			`## Documentation Site`

			`The full documentation is published at [skywalker-1.warehack.ing](https://skywalker-1.warehack.ing) and covers:`

			`\| Section \| Pages \| Covers \|`
			`\|---------\|-------\|--------\|`
			`\| Hardware \| 4 \| Board architecture, GPIO pin map, RF specifications \|`
			`\| USB Interface \| 4 \| 30 vendor commands, boot sequence, endpoint layout \|`
			`\| BCM4500 \| 5 \| Register map, indirect access protocol, tuning sequence, GPIF streaming, signal monitoring \|`
			`\| LNB & DiSEqC \| 3 \| Voltage/tone control, DiSEqC 1.0/1.2, legacy Dish switches \|`
			`\| I2C Bus \| 2 \| Bus architecture, STOP corruption bug root cause analysis \|`
			`\| Firmware \| 7 \| 5 stock versions compared, custom v3.01 and v3.02, storage formats \|`
			`\| Driver \| 2 \| Linux gp8psk kernel driver, DVB-S2 incompatibility investigation \|`
			`\| Tools \| 7 \| Every Python utility documented with usage examples \|`
			`\| Reference \| 1 \| Consolidated master reference (registers, commands, GPIO, I2C) \|`

			`To run the docs site locally:`

			```bash
			`cd site`
			`npm install`
			`npm run dev # http://localhost:4321`
			```

			`<details>`
			`<summary>Docker deployment</summary>`

			`The docs site includes a multi-stage Dockerfile with dev and prod targets. Production serves static files through Caddy.`

			```bash
			`cd site`

			`# Development (HMR via volume mounts)`
			`APP_ENV=dev docker compose up --build`

			`# Production (static build served by Caddy)`
			`APP_ENV=prod docker compose up --build -d`
			```

			`</details>`

			`## Project History`

			This project started with USB packet captures and `lsusb` output, then progressed through increasingly deep layers of the hardware:

			`1. EEPROM extraction -- dumped raw firmware bytes over I2C`
			`2. Ghidra disassembly -- decompiled five 8051 firmware images, mapped all functions and vendor commands`
			`3. Windows driver analysis -- cross-referenced Ghidra findings against Genpix BDA driver source`
			4. Linux driver analysis -- mapped kernel `gp8psk` driver to decoded vendor commands
			`5. Custom firmware -- wrote a full replacement in C, discovered and fixed the [I2C STOP corruption bug](https://skywalker-1.warehack.ing/i2c/stop-corruption-bug/)`
			`6. RF tooling -- built spectrum analyzer, blind scanner, and signal monitor on top of the custom command set`

			`## Contributing`

			`This is a niche reverse-engineering project for a specific piece of satellite hardware. If you have a SkyWalker-1 (or other Genpix device using the BCM4500), contributions are welcome -- particularly additional firmware dumps, register documentation, or corrections to the analysis.`

			`## License`

			The custom firmware source, Python tools, and documentation are open source. Stock firmware binaries in `firmware-dump/` are proprietary Genpix Electronics images retained for research and interoperability purposes.