Add Starlight documentation site (32 pages, 9 sidebar groups)
Astro 5 + Starlight 0.37 site at site/ with teal/steel theme. Content sourced from 14 reverse engineering docs, master reference, and custom firmware source. Includes Tabs, Badge, Steps, Aside, FileTree, and CardGrid components throughout. DiSEqC SVGs with click-to-zoom via starlight-image-zoom. All internal links validated. Pagefind search indexes all 32 pages.
This commit is contained in:
parent
f1d4f4f010
commit
b21f4957f6
42 changed files with 15635 additions and 0 deletions
259
site/src/content/docs/tools/debugging.mdx
Normal file
259
site/src/content/docs/tools/debugging.mdx
Normal file
|
|
@ -0,0 +1,259 @@
|
|||
---
|
||||
title: Debugging Tools
|
||||
description: Hardware diagnostic tools for boot testing, I2C bus debugging, and firmware extraction.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Steps, Aside, Badge } from '@astrojs/starlight/components';
|
||||
|
||||
The `tools/` directory includes a suite of diagnostic scripts developed during the reverse engineering of the SkyWalker-1. These tools were instrumental in isolating the I2C STOP corruption bug in the FX2 controller and verifying correct BCM4500 initialization.
|
||||
|
||||
All debugging tools require `pyusb`, root access, and the kernel `dvb_usb_gp8psk` module to be unloaded.
|
||||
|
||||
```bash
|
||||
pip install pyusb
|
||||
sudo modprobe -r dvb_usb_gp8psk gp8psk_fe
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Boot Tests">
|
||||
|
||||
## Boot Testing Tools
|
||||
|
||||
Two scripts test the BCM4500 boot sequence using debug modes in the custom v3.01.0 firmware.
|
||||
|
||||
### test_boot.py -- Full Boot Verification
|
||||
|
||||
Runs a complete BOOT_8PSK sequence and reports success or failure with detailed register readback.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/test_boot.py
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
|
||||
<Steps>
|
||||
1. Reads firmware version via `GET_FW_VERS` (0x92)
|
||||
2. Reads config status via `GET_8PSK_CONFIG` (0x80)
|
||||
3. Sends `BOOT_8PSK` (0x89, wValue=1) with a 10-second timeout
|
||||
4. Decodes the 3-byte response: config status, boot stage, probe byte
|
||||
5. On success: reads BCM4500 direct registers (0xA2--0xA8), indirect registers (pages 0x00--0x0F), I2C diagnostic data, signal strength, and lock status
|
||||
6. On failure: runs I2C bus scan (0xB4), attempts raw I2C reads to BCM4500
|
||||
</Steps>
|
||||
|
||||
**Boot stage codes:**
|
||||
|
||||
| Stage | Code | Meaning |
|
||||
|-------|------|---------|
|
||||
| `NOT_STARTED` | 0x00 | Boot not attempted |
|
||||
| `GPIO_SETUP` | 0x01 | GPIO pins configured |
|
||||
| `PWR_SETTLED` | 0x02 | Power-on delay complete |
|
||||
| `I2C_PROBE` | 0x03 | Probing BCM4500 on I2C |
|
||||
| `INIT_BLK0` | 0x04 | Writing init block 0 |
|
||||
| `INIT_BLK1` | 0x05 | Writing init block 1 |
|
||||
| `INIT_BLK2` | 0x06 | Writing init block 2 |
|
||||
| `COMPLETE` | 0xFF | Boot finished |
|
||||
|
||||
**Config status flags after successful boot:**
|
||||
|
||||
| Flag | Bit | Expected |
|
||||
|------|-----|----------|
|
||||
| `bm8pskStarted` | 0x01 | <Badge text="ON" variant="success" /> |
|
||||
| `bm8pskFW_Loaded` | 0x02 | <Badge text="ON" variant="success" /> |
|
||||
|
||||
### test_boot_debug.py -- Incremental Stage Testing
|
||||
|
||||
Sends debug boot modes (wValue=0x80 through 0x83) one at a time to isolate which stage of the boot sequence fails. Can test a single stage or run all sequentially.
|
||||
|
||||
```bash title="Run all debug stages"
|
||||
sudo python3 tools/test_boot_debug.py
|
||||
```
|
||||
|
||||
```bash title="Test only stage 0x82"
|
||||
sudo python3 tools/test_boot_debug.py 0x82
|
||||
```
|
||||
|
||||
**Debug modes:**
|
||||
|
||||
| wValue | Action | Tests |
|
||||
|--------|--------|-------|
|
||||
| `0x80` | No-op: return current state | Firmware responsive? |
|
||||
| `0x81` | GPIO setup + power + delays (no I2C) | Power rails working? |
|
||||
| `0x82` | GPIO + I2C bus reset + BCM4500 probe | I2C communication working? |
|
||||
| `0x83` | GPIO + I2C probe + write init block 0 | Register writes accepted? |
|
||||
|
||||
Each mode returns a 3-byte response: config status, boot stage, and probe byte. The tool reports timing (ms) for each stage and checks if the device is still responsive after failures.
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="I2C Tests">
|
||||
|
||||
## I2C Debugging Suite
|
||||
|
||||
Three scripts that implement a progressive isolation methodology to identify I2C bus faults. These were developed in sequence, each informed by the results of the previous one.
|
||||
|
||||
### Methodology
|
||||
|
||||
<Steps>
|
||||
1. **Broad scan** (`test_i2c_debug.py`) -- Power on the BCM4500 and probe the entire I2C bus. Does the chip respond at any address?
|
||||
2. **Isolation** (`test_i2c_isolate.py`) -- Determine whether the fault is in the BCM4500, the I2C bus, or the FX2 controller. Test the chip when already powered vs. after a reset.
|
||||
3. **Pinpoint** (`test_i2c_pinpoint.py`) -- Identify the exact operation that corrupts communication. Compare I2C read-only, GPIO+reset, and GPIO+bus-reset+probe modes.
|
||||
</Steps>
|
||||
|
||||
### test_i2c_debug.py -- Bus Discovery
|
||||
|
||||
Powers on the BCM4500 via GPIO-only mode (0x81), then runs progressively detailed diagnostics.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/test_i2c_debug.py
|
||||
```
|
||||
|
||||
**Test sequence:**
|
||||
|
||||
| Step | Action | Purpose |
|
||||
|------|--------|---------|
|
||||
| 1 | Send mode 0x81 (GPIO power on) | Start BCM4500 without any I2C |
|
||||
| 2 | I2C bus scan (0xB4) immediately | Check for devices right after power-on |
|
||||
| 3 | Wait 500 ms, scan again | Maybe chip needs more time? |
|
||||
| 4 | Raw I2C reads to candidate addresses | Try 0x08, 0x09, 0x0A, 0x0B, 0x10, 0x11, 0x68, 0x69, 0x60, 0x61 |
|
||||
| 5 | Check I2C controller state | Observe bus health |
|
||||
| 6 | Send mode 0x82 after 1s delay | Test probe with extra settling time |
|
||||
|
||||
**Candidate addresses** cover different BCM4500 pin-strap configurations and common demodulator/tuner addresses.
|
||||
|
||||
### test_i2c_isolate.py -- Fault Isolation
|
||||
|
||||
Determines whether the failure is caused by `bcm_direct_read`, re-reset timing, or the I2C bus reset (bmSTOP).
|
||||
|
||||
```bash
|
||||
sudo python3 tools/test_i2c_isolate.py
|
||||
```
|
||||
|
||||
**Test sequence:**
|
||||
|
||||
| Test | Action | Question |
|
||||
|------|--------|----------|
|
||||
| **A** | Power on (0x81), wait 1s, raw read | Is BCM4500 alive from cold start? |
|
||||
| **B** | Run mode 0x82 (re-resets + probe) | Does `bcm_direct_read` work after reset? |
|
||||
| **C** | Immediately raw read after 0x82 | Is I2C function itself broken? |
|
||||
| **D** | Raw reads at 100, 200, 500, 1000, 2000 ms | Is it a timing issue? |
|
||||
| **E** | Re-power (0x81), wait, then 0x82 | Repeatable? |
|
||||
|
||||
### test_i2c_pinpoint.py -- Root Cause Identification
|
||||
|
||||
The definitive test that identified the I2C STOP corruption bug. Compares three modes on a chip that is already proven alive.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/test_i2c_pinpoint.py
|
||||
```
|
||||
|
||||
**Test sequence:**
|
||||
|
||||
<Steps>
|
||||
1. Power on BCM4500 via mode 0x81, confirm alive with raw read
|
||||
2. **Mode 0x84**: `bcm_direct_read` only (no GPIO, chip already powered) -- tests if the read function itself is broken
|
||||
3. **Mode 0x85**: GPIO + reset + power but NO I2C bus reset (no `bmSTOP`) -- tests if re-reset breaks things
|
||||
4. **Mode 0x82**: GPIO + I2C `bmSTOP` + reset + power + probe -- the mode that was failing
|
||||
</Steps>
|
||||
|
||||
**Interpretation:**
|
||||
|
||||
| Result Pattern | Diagnosis |
|
||||
|----------------|-----------|
|
||||
| 0x84 works, 0x85 works, 0x82 fails | `bmSTOP` (I2C bus reset) is the culprit |
|
||||
| 0x84 fails | `bcm_direct_read` has a bug |
|
||||
| 0x85 fails | Re-reset timing needs more delay |
|
||||
|
||||
<Aside type="note">
|
||||
This test conclusively proved that the spurious `I2CS |= bmSTOP` in the boot sequence was corrupting the FX2 I2C controller. Mode 0x84 succeeded immediately after 0x82 failed, proving the BCM4500 was alive the entire time -- only the FX2 controller was in a bad state. See [I2C STOP Corruption Bug](/i2c/stop-corruption-bug/) for the full analysis.
|
||||
</Aside>
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Memory Extraction">
|
||||
|
||||
## Windows Memory Dump (wine_memdump.py)
|
||||
|
||||
Extracts firmware from the Genpix Windows driver/updater by running it under Wine and dumping process memory. The Windows updater executable contains embedded firmware images that are unpacked into memory at runtime.
|
||||
|
||||
<Aside type="note">
|
||||
This tool requires **Wine** to be installed. It reads `/proc/PID/mem` and `/proc/PID/maps`, which requires running as the same user as the Wine process or as root.
|
||||
</Aside>
|
||||
|
||||
```bash
|
||||
sudo python3 tools/wine_memdump.py SkyWalkerUpdater.exe
|
||||
```
|
||||
|
||||
```bash title="Attach to an already-running Wine process"
|
||||
sudo python3 tools/wine_memdump.py SkyWalkerUpdater.exe --skip-launch
|
||||
```
|
||||
|
||||
```bash title="Custom output directory and wait time"
|
||||
sudo python3 tools/wine_memdump.py SkyWalkerUpdater.exe -o dumps/ --wait 5
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `EXE` | Windows PE executable to run under Wine (positional, required) |
|
||||
| `-o, --output-dir DIR` | Output directory for dumps (default: `.`) |
|
||||
| `--wait SECONDS` | Seconds to wait after launch for unpacking (default: `3`) |
|
||||
| `--skip-launch` | Attach to an already-running Wine process |
|
||||
|
||||
### How It Works
|
||||
|
||||
<Steps>
|
||||
1. Launches the `.exe` under Wine with `WINEDEBUG=-all` to suppress noise
|
||||
2. Waits for the process to unpack (configurable delay)
|
||||
3. Finds the Wine process PID by scanning `/proc`
|
||||
4. Reads `/proc/PID/maps` to identify readable memory regions
|
||||
5. Reads each region from `/proc/PID/mem` into a contiguous dump
|
||||
6. Saves the full dump (`wine_memdump.bin`) and region map (`wine_memdump_regions.txt`)
|
||||
7. Searches the dump for firmware signatures
|
||||
</Steps>
|
||||
|
||||
### Firmware Signature Search
|
||||
|
||||
The tool searches for 7 categories of signatures:
|
||||
|
||||
| Search | Pattern | Purpose |
|
||||
|--------|---------|---------|
|
||||
| C2 EEPROM headers | `C2 C0 09 03 02` | Find embedded firmware images |
|
||||
| FX2 init sequence | `78 7F E4 F6 D8 FD 75 81` | FX2 RAM clear/init code |
|
||||
| RAM clear pattern | `78 7F E4 F6 D8 FD` | Partial match variant |
|
||||
| C2 load records | LEN + addr `0x0000` + `LJMP` | Record chain starts |
|
||||
| VID references | `C0 09` near `03 02` | VID/PID byte pairs |
|
||||
| Version strings | `2.13`, `SkyWalker`, `Genpix`, `8PSK`, etc. | Text markers |
|
||||
| USB transfer setup | `0x40 0xA0`, `0x40 0x83`, `0x40 0x84` | WinUSB vendor request patterns |
|
||||
|
||||
Each hit is reported with the dump offset, virtual address, containing memory region, and context bytes.
|
||||
|
||||
### Output Files
|
||||
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| `wine_memdump.bin` | Full concatenated memory dump |
|
||||
| `wine_memdump_regions.txt` | Region map with virtual addresses, permissions, and dump offsets |
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Diagnostic Command Reference
|
||||
|
||||
The custom v3.01.0 firmware adds these diagnostic vendor commands used by the test scripts:
|
||||
|
||||
| Command | Code | Direction | Purpose |
|
||||
|---------|------|-----------|---------|
|
||||
| `I2C_BUS_SCAN` | 0xB4 | IN | Probe all 128 I2C addresses, return 16-byte bitmap |
|
||||
| `I2C_RAW_READ` | 0xB5 | IN | Read from any I2C device (wValue=addr, wIndex=reg) |
|
||||
| `I2C_DIAG` | 0xB6 | IN | Step-by-step indirect register read with intermediate values |
|
||||
| `RAW_DEMOD_READ` | 0xB1 | IN | Read any BCM4500 indirect register |
|
||||
| `RAW_DEMOD_WRITE` | 0xB2 | OUT | Write any BCM4500 indirect register |
|
||||
|
||||
These commands are only available when running the custom firmware. Stock firmware will STALL on these command codes.
|
||||
|
||||
## See Also
|
||||
|
||||
- [I2C STOP Corruption Bug](/i2c/stop-corruption-bug/) -- the bug these tools helped discover
|
||||
- [Boot Sequence](/usb/boot-sequence/) -- the initialization flow being tested
|
||||
- [Custom Firmware v3.01.0](/firmware/custom-v301/) -- the firmware that enables debug modes
|
||||
- [I2C Bus Architecture](/i2c/bus-architecture/) -- I2C protocol and controller details
|
||||
- [Firmware Loader](/tools/firmware-loader/) -- load custom firmware before running debug tools
|
||||
266
site/src/content/docs/tools/eeprom-utilities.mdx
Normal file
266
site/src/content/docs/tools/eeprom-utilities.mdx
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
---
|
||||
title: EEPROM Utilities
|
||||
description: EEPROM read, write, probe, and verification tools for the FX2 configuration EEPROM.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Steps, Aside, Badge } from '@astrojs/starlight/components';
|
||||
|
||||
Three tools manage the SkyWalker-1's I2C EEPROM (24Cxx-family at address `0x51`): `eeprom_write.py` for flashing firmware images, `eeprom_dump.py` for reading EEPROM contents, and `eeprom_probe.py` for testing I2C addressing methods.
|
||||
|
||||
The EEPROM stores the Cypress FX2 boot firmware in C2 IIC format. The FX2 loads this firmware automatically on every power-up. Writing incorrect data to the EEPROM will prevent the device from enumerating on USB.
|
||||
|
||||
<Aside type="danger">
|
||||
**Writing incorrect firmware to the EEPROM can brick the device.** The SkyWalker-1 boots exclusively from this EEPROM on power-up. A corrupted image means no USB enumeration -- the device will appear dead until the EEPROM is reprogrammed using either the FX2 boot ROM's `0xA0` vendor request (if accessible) or an external I2C programmer.
|
||||
|
||||
Always back up the current EEPROM contents before flashing.
|
||||
</Aside>
|
||||
|
||||
```bash
|
||||
pip install pyusb
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Flash (eeprom_write.py)">
|
||||
|
||||
## EEPROM Flash Tool
|
||||
|
||||
`eeprom_write.py` is the full-featured EEPROM management tool with four subcommands.
|
||||
|
||||
### Subcommands
|
||||
|
||||
| Subcommand | Purpose |
|
||||
|------------|---------|
|
||||
| `info` | Parse and display C2 header from a `.bin` file (offline, no device needed) |
|
||||
| `backup` | Dump current EEPROM contents to a file |
|
||||
| `verify` | Compare a `.bin` file against current EEPROM contents |
|
||||
| `flash` | Write a C2 firmware image to the EEPROM |
|
||||
|
||||
### info -- Inspect a C2 Image File
|
||||
|
||||
Parse and display the C2 header and load records from a firmware binary without connecting to the device.
|
||||
|
||||
```bash
|
||||
python3 tools/eeprom_write.py info firmware.bin
|
||||
```
|
||||
|
||||
```
|
||||
C2 Image: firmware.bin
|
||||
File size: 9512 bytes
|
||||
========================================
|
||||
|
||||
Header:
|
||||
Format: C2 (Large EEPROM, code loads to internal RAM)
|
||||
VID: 0x09C0 (Genpix)
|
||||
PID: 0x0203 (SkyWalker-1)
|
||||
DID: 0x0000
|
||||
Config: 0x40 (400kHz I2C)
|
||||
|
||||
Load Records:
|
||||
[0] 1023 bytes -> 0x0000-0x03FE [02 18 8d 78 7f e4 f6 d8...]
|
||||
[1] 1023 bytes -> 0x03FF-0x07FD [...]
|
||||
...
|
||||
[9] 115 bytes -> 0x23F7-0x2469 [...]
|
||||
[10] END MARKER -> entry point: 0xE600
|
||||
|
||||
Total firmware: 9472 bytes in 10 segments
|
||||
Entry point: 0xE600 (LJMP target after boot)
|
||||
|
||||
EEPROM footprint: 9512 bytes (0x2528)
|
||||
```
|
||||
|
||||
### backup -- Read EEPROM to File
|
||||
|
||||
```bash
|
||||
sudo python3 tools/eeprom_write.py backup -o my_backup.bin
|
||||
```
|
||||
|
||||
```bash title="Specify read size"
|
||||
sudo python3 tools/eeprom_write.py backup -o my_backup.bin --max-size 16384
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-o, --output FILE` | Output file (default: `skywalker1_eeprom.bin`) |
|
||||
| `--max-size BYTES` | Maximum bytes to read (default: `16384`) |
|
||||
|
||||
### verify -- Compare Image Against EEPROM
|
||||
|
||||
Read the EEPROM and compare byte-by-byte against a local `.bin` file. Reports any mismatches with offset and expected vs. actual values.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/eeprom_write.py verify firmware.bin
|
||||
```
|
||||
|
||||
Exit code `0` = match, `1` = mismatch.
|
||||
|
||||
### flash -- Write Image to EEPROM
|
||||
|
||||
The flash workflow includes built-in safety measures: image validation, VID/PID check, automatic backup, countdown timer, write verification.
|
||||
|
||||
<Steps>
|
||||
1. **Validate** the C2 image file (header format, VID/PID match, record integrity)
|
||||
2. **Connect** to the SkyWalker-1 and check device VID/PID against the image
|
||||
3. **Backup** the current EEPROM contents to a timestamped file
|
||||
4. **Wait** 3 seconds with a countdown (Ctrl-C to abort)
|
||||
5. **Write** the image in 16-byte page-aligned chunks with 10 ms write cycle delays
|
||||
6. **Verify** by reading back and comparing every byte
|
||||
</Steps>
|
||||
|
||||
```bash title="Flash with all safety checks"
|
||||
sudo python3 tools/eeprom_write.py flash firmware.bin
|
||||
```
|
||||
|
||||
```bash title="Dry run (shows what would happen, writes nothing)"
|
||||
sudo python3 tools/eeprom_write.py flash firmware.bin --dry-run
|
||||
```
|
||||
|
||||
```bash title="Skip backup (not recommended)"
|
||||
sudo python3 tools/eeprom_write.py flash firmware.bin --no-backup
|
||||
```
|
||||
|
||||
```bash title="Force flash with VID/PID mismatch"
|
||||
sudo python3 tools/eeprom_write.py flash firmware.bin --force
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `FILE` | C2 firmware image (positional, required) |
|
||||
| `--dry-run` | Validate and show plan without writing |
|
||||
| `--no-backup` | Skip pre-flash EEPROM backup |
|
||||
| `--force` | Override VID/PID mismatch check |
|
||||
|
||||
### EEPROM Write Parameters
|
||||
|
||||
| Parameter | Value |
|
||||
|-----------|-------|
|
||||
| I2C slave address | `0x51` (7-bit) |
|
||||
| Vendor command (write) | `I2C_WRITE` (`0x83`) |
|
||||
| Vendor command (read) | `I2C_READ` (`0x84`) |
|
||||
| Page size | 16 bytes (conservative for 24Cxx) |
|
||||
| Write cycle time | 10 ms per page |
|
||||
| Maximum image size | 16,384 bytes (16 KB) |
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Dump (eeprom_dump.py)">
|
||||
|
||||
## EEPROM Dump Tool
|
||||
|
||||
`eeprom_dump.py` is a simpler read-only tool focused on extracting and analyzing EEPROM contents.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/eeprom_dump.py -o eeprom.bin
|
||||
```
|
||||
|
||||
```bash title="Extract flat binary + 64K Ghidra image"
|
||||
sudo python3 tools/eeprom_dump.py -o eeprom.bin --extract
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-o, --output FILE` | Output file (default: `skywalker1_eeprom.bin`) |
|
||||
| `--extract` | Extract firmware as flat binary + full 64K image |
|
||||
| `--max-size BYTES` | Maximum EEPROM size to read (default: `16384`) |
|
||||
|
||||
### Auto-Detect End of Data
|
||||
|
||||
The tool detects the end of valid data by watching for consecutive `0xFF` chunks (4 or more = end of programmed region). This avoids reading the entire EEPROM when only the first few KB contain firmware.
|
||||
|
||||
### Extract Mode (--extract)
|
||||
|
||||
When `--extract` is specified, the tool additionally produces:
|
||||
|
||||
- **`*_flat.bin`** -- firmware code extracted from C2 records, stored as a flat binary covering only the used address range
|
||||
- **`*_full64k.bin`** -- full 64 KB memory image (unused regions filled with `0xFF`), suitable for loading in Ghidra at base address `0x0000`
|
||||
|
||||
### Output
|
||||
|
||||
```
|
||||
Genpix SkyWalker-1 EEPROM Dump
|
||||
========================================
|
||||
Found device: Bus 1 Addr 12
|
||||
|
||||
Reading EEPROM (max 16384 bytes)...
|
||||
End of data at 0x2600 (0xFF padding)
|
||||
Read 9728 bytes total
|
||||
Saved raw EEPROM to: eeprom.bin
|
||||
|
||||
========================================
|
||||
EEPROM Header:
|
||||
Format: C2 (Large EEPROM, code loads to internal RAM)
|
||||
VID: 0x09C0 (Genpix)
|
||||
PID: 0x0203 (SkyWalker-1)
|
||||
DID: 0x0000
|
||||
Config: 0x40 (400kHz I2C)
|
||||
|
||||
Load Records:
|
||||
[0] 1023 bytes -> 0x0000-0x03FE [02 18 8d 78 7f e4 f6 d8...]
|
||||
...
|
||||
[10] END MARKER -> entry point: 0xE600
|
||||
|
||||
Total firmware: 9472 bytes in 10 records
|
||||
Entry point: 0xE600 (LJMP target after boot)
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Probe (eeprom_probe.py)">
|
||||
|
||||
## EEPROM Address Probe
|
||||
|
||||
`eeprom_probe.py` is a diagnostic script that tests different I2C addressing methods to determine how the Genpix firmware's `I2C_READ`/`I2C_WRITE` commands interpret `wValue` and `wIndex` parameters for EEPROM access.
|
||||
|
||||
This is a developer tool used during reverse engineering. It runs 7 different addressing approaches and checks each result against known reference bytes from the EEPROM header.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/eeprom_probe.py
|
||||
```
|
||||
|
||||
### Test Approaches
|
||||
|
||||
| Approach | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| 1 | `I2C_WRITE data=[addr_h, addr_l]` then `I2C_READ` | Set EEPROM offset via write data |
|
||||
| 2 | `wValue=addr, wIndex=slave` | Reversed parameter mapping |
|
||||
| 3 | `wValue=slave, wIndex=addr` | Standard Genpix mapping |
|
||||
| 4 | `I2C_READ wIndex=offset` | Offset in wIndex field |
|
||||
| 5 | `wValue=(slave<<8\|offset)` | Packed slave + offset |
|
||||
| 6 | `wValue=offset (no slave)` | Offset only, no slave address |
|
||||
| 7 | Larger reads (64 bytes) | Verify sequential data across page boundaries |
|
||||
|
||||
### Known Reference Bytes
|
||||
|
||||
The script compares against two known patterns:
|
||||
|
||||
- **Offset 0x0000**: `C2 C0 09 03 02 00 00 40` (C2 header: marker, VID, PID, DID, config)
|
||||
- **Offset 0x0008**: `03 FF 00 00 02 18 8D 30` (first load record)
|
||||
|
||||
<Aside type="note">
|
||||
This tool confirmed that the Genpix firmware uses `wValue=slave_address` (0x51) and `wIndex=eeprom_offset` for the `I2C_READ` (0x84) command. Approach 4 is the correct protocol.
|
||||
</Aside>
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Cypress C2 Boot Format
|
||||
|
||||
The EEPROM stores firmware in the Cypress C2 IIC second-stage boot format:
|
||||
|
||||
| Field | Offset | Size | Description |
|
||||
|-------|--------|------|-------------|
|
||||
| Marker | 0 | 1 | `0xC2` (large EEPROM, external memory) |
|
||||
| VID | 1 | 2 | USB Vendor ID, little-endian (`0x09C0`) |
|
||||
| PID | 3 | 2 | USB Product ID, little-endian (`0x0203`) |
|
||||
| DID | 5 | 2 | Device ID, little-endian |
|
||||
| Config | 7 | 1 | Boot config (`0x40` = 400 kHz I2C) |
|
||||
| Records | 8+ | var | Code segments: `[len_hi][len_lo][addr_hi][addr_lo][data...]` |
|
||||
| End | last | 4 | `[0x80][0x01][entry_hi][entry_lo]` (entry point = `0xE600`) |
|
||||
|
||||
For a full description of the storage format, see [Firmware Storage Formats](/firmware/storage-formats/).
|
||||
|
||||
## See Also
|
||||
|
||||
- [Firmware Loader](/tools/firmware-loader/) -- RAM-based firmware loading (non-destructive)
|
||||
- [Storage Formats](/firmware/storage-formats/) -- C2 format, hexline, and FW02 chunk details
|
||||
- [Version Comparison](/firmware/version-comparison/) -- differences across firmware versions
|
||||
- [I2C Bus Architecture](/i2c/bus-architecture/) -- I2C protocol details
|
||||
255
site/src/content/docs/tools/firmware-loader.mdx
Normal file
255
site/src/content/docs/tools/firmware-loader.mdx
Normal file
|
|
@ -0,0 +1,255 @@
|
|||
---
|
||||
title: Firmware Loader
|
||||
description: RAM firmware loader and firmware dump/probe utilities for the Genpix SkyWalker-1.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Steps, Aside, Badge } from '@astrojs/starlight/components';
|
||||
|
||||
Two complementary tools handle firmware on the SkyWalker-1: `fw_load.py` loads firmware into FX2 RAM for testing, and `fw_dump.py` extracts firmware and device information from a running device.
|
||||
|
||||
Both tools require `pyusb` and typically need root access (or appropriate udev rules) to communicate with the USB device.
|
||||
|
||||
```bash
|
||||
pip install pyusb
|
||||
```
|
||||
|
||||
<Aside type="danger">
|
||||
**RAM loading is non-destructive.** The `fw_load.py` tool writes to volatile FX2 RAM only -- it never touches the EEPROM. Power-cycling the device restores the factory-programmed firmware. For permanent EEPROM programming, see [EEPROM Utilities](/tools/eeprom-utilities/).
|
||||
</Aside>
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="Loading (fw_load.py)">
|
||||
|
||||
## RAM Firmware Loader
|
||||
|
||||
`fw_load.py` loads firmware into the Cypress FX2 internal/external RAM via the standard `0xA0` vendor request built into the FX2 silicon boot ROM. This is the primary tool for firmware development: load, test, power-cycle to revert.
|
||||
|
||||
### Subcommands
|
||||
|
||||
| Subcommand | Purpose |
|
||||
|------------|---------|
|
||||
| `load` | Load a firmware file into FX2 RAM |
|
||||
| `reset` | Halt and restart the FX2 CPU |
|
||||
| `read` | Read and hex-dump FX2 RAM contents |
|
||||
|
||||
### load -- Write Firmware to RAM
|
||||
|
||||
<Steps>
|
||||
1. **Halt the CPU** -- writes `0x01` to the CPUCS register at `0xE600`
|
||||
2. **Write code segments** into RAM in 64-byte chunks via vendor request `0xA0`
|
||||
3. **Start the CPU** -- writes `0x00` to CPUCS, triggering USB re-enumeration
|
||||
</Steps>
|
||||
|
||||
**Supported file formats:**
|
||||
|
||||
| Extension | Format | Load Address |
|
||||
|-----------|--------|-------------|
|
||||
| `.ihx`, `.hex` | Intel HEX | Addresses embedded in file |
|
||||
| `.bix`, `.bin` | Raw binary | `0x0000` (start of internal RAM) |
|
||||
|
||||
**Options:**
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `FILE` | Firmware file path (positional, required) |
|
||||
| `--no-reset` | Load segments without halting/starting the CPU |
|
||||
| `--wait SECONDS` | Wait for USB re-enumeration after load |
|
||||
| `-v, --verbose` | Show per-chunk transfer progress |
|
||||
| `--force` | Allow loading to devices with unknown VID/PID |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash title="Load custom firmware and wait for re-enumeration"
|
||||
sudo python3 tools/fw_load.py load firmware/build/skywalker1.ihx --wait 3
|
||||
```
|
||||
|
||||
```bash title="Load raw binary with verbose output"
|
||||
sudo python3 tools/fw_load.py load firmware.bix -v --wait 5
|
||||
```
|
||||
|
||||
```bash title="Load without CPU reset (write segments only)"
|
||||
sudo python3 tools/fw_load.py load firmware.ihx --no-reset
|
||||
```
|
||||
|
||||
**Typical output:**
|
||||
|
||||
```
|
||||
SkyWalker-1 RAM Firmware Loader
|
||||
========================================
|
||||
|
||||
Firmware: firmware/build/skywalker1.ihx
|
||||
Segments: 3
|
||||
Total size: 3072 bytes
|
||||
Address: 0x0000 - 0x0BFF
|
||||
|
||||
Found SkyWalker-1: Bus 1 Addr 12 (VID 0x09C0 PID 0x0203)
|
||||
|
||||
[1/3] Halting CPU (CPUCS = 0x01)...
|
||||
CPU halted
|
||||
|
||||
[2/3] Loading 3 segment(s) into RAM...
|
||||
0x0000-0x03FF (1024 bytes)
|
||||
0x0400-0x07FF (1024 bytes)
|
||||
0x0800-0x0BFF (1024 bytes)
|
||||
|
||||
3072 bytes loaded
|
||||
|
||||
[3/3] Starting CPU (CPUCS = 0x00)...
|
||||
CPU released
|
||||
|
||||
Firmware is running. The device will re-enumerate
|
||||
with new USB descriptors if the firmware does so.
|
||||
```
|
||||
|
||||
### reset -- Restart the FX2 CPU
|
||||
|
||||
Halts and restarts the CPU without loading new code. Useful for triggering USB re-enumeration when the device is in a bad state.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/fw_load.py reset --wait 3
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--wait SECONDS` | Wait for re-enumeration after reset |
|
||||
| `--force` | Allow reset on unknown VID/PID |
|
||||
|
||||
### read -- Hex-Dump FX2 RAM
|
||||
|
||||
Read memory contents from a running FX2. Useful for verifying loaded firmware or inspecting register state.
|
||||
|
||||
```bash title="Read first 256 bytes of internal RAM"
|
||||
sudo python3 tools/fw_load.py read --addr 0x0000 --len 256
|
||||
```
|
||||
|
||||
```bash title="Check CPUCS register"
|
||||
sudo python3 tools/fw_load.py read --addr 0xe600 --len 1
|
||||
```
|
||||
|
||||
```bash title="Dump to file"
|
||||
sudo python3 tools/fw_load.py read --addr 0x0000 --len 8192 -o ram_dump.bin
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--addr ADDR` | Start address in hex (default: `0x0000`) |
|
||||
| `--len LENGTH` | Bytes to read (default: `256`) |
|
||||
| `-o, --output FILE` | Save raw bytes to file |
|
||||
| `--force` | Allow read on unknown VID/PID |
|
||||
|
||||
### Device Detection
|
||||
|
||||
The loader searches for devices in this order:
|
||||
|
||||
1. **SkyWalker-1** -- VID `0x09C0`, PID `0x0203`
|
||||
2. **Bare Cypress FX2** -- VID `0x04B4`, PID `0x8613` (unprogrammed/blank EEPROM)
|
||||
|
||||
Use `--force` to override VID/PID checks for devices with non-standard descriptors.
|
||||
|
||||
<Aside type="tip">
|
||||
**Recovery procedure:** If the device is completely hung (not responding to vendor commands), you can still recover it using `fw_load.py`. The FX2's `0xA0` vendor request is handled by the boot ROM in silicon, not by user firmware. Even a hung 8051 CPU can be halted and reprogrammed via this mechanism.
|
||||
</Aside>
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Dumping (fw_dump.py)">
|
||||
|
||||
## Firmware Probe and Dump Tool
|
||||
|
||||
`fw_dump.py` queries device information, dumps FX2 RAM contents, and scans for undocumented vendor commands.
|
||||
|
||||
### Options
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--info` | Query and display device information |
|
||||
| `--dump FILE` | Dump FX2 RAM to a binary file |
|
||||
| `--scan` | Brute-force scan all vendor commands (0x00--0xFF) |
|
||||
| `--start ADDR` | RAM dump start address (default: `0x0000`) |
|
||||
| `--size SIZE` | RAM dump size in bytes (default: `0x2000` = 8 KB) |
|
||||
| `--external` | Attempt to dump external RAM (64 KB) |
|
||||
|
||||
Running with no flags defaults to `--info --scan`.
|
||||
|
||||
### Device Info (--info)
|
||||
|
||||
Queries all known Genpix vendor commands and displays firmware version, build date, USB speed, serial number, and the 8PSK configuration status byte with decoded flags.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/fw_dump.py --info
|
||||
```
|
||||
|
||||
```
|
||||
=== Genpix SkyWalker-1 Device Info ===
|
||||
|
||||
FW Version: 2.06.4 (0x020604)
|
||||
FW Build: 2007-07-13
|
||||
BCD Version: 0206
|
||||
Vendor: Genpix
|
||||
Product: SkyWalker-1
|
||||
USB Speed: High (480Mbps)
|
||||
Serial: 00000000
|
||||
Config: 0x03
|
||||
[ ON] 8PSK Started
|
||||
[ ON] BCM4500 FW Loaded
|
||||
[off] Intersil LNB On
|
||||
[off] DVB Mode
|
||||
[off] 22kHz Tone
|
||||
[off] 18V Selected
|
||||
[off] DC Tuned
|
||||
[off] Armed (streaming)
|
||||
```
|
||||
|
||||
### Vendor Command Scan (--scan)
|
||||
|
||||
Sends vendor IN requests to every command index from `0x00` to `0xFF` and reports which ones return data. Commands already documented in the reference are labeled `[KNOWN]`; unexpected responses are flagged `[NEW!]`.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/fw_dump.py --scan
|
||||
```
|
||||
|
||||
### RAM Dump (--dump)
|
||||
|
||||
Reads FX2 internal RAM (8 KB at `0x0000`--`0x1FFF`) or external RAM (up to 64 KB with `--external`) via the standard `0xA0` vendor request.
|
||||
|
||||
```bash title="Dump internal RAM"
|
||||
sudo python3 tools/fw_dump.py --dump internal_ram.bin
|
||||
```
|
||||
|
||||
```bash title="Dump external RAM (64 KB)"
|
||||
sudo python3 tools/fw_dump.py --dump external_ram.bin --external
|
||||
```
|
||||
|
||||
```bash title="Dump specific range"
|
||||
sudo python3 tools/fw_dump.py --dump region.bin --start 0x1000 --size 0x800
|
||||
```
|
||||
|
||||
The tool performs a quick analysis of the dump, reporting non-`0xFF` byte count and checking for the standard FX2 reset vector (`LJMP` at address `0x0000`).
|
||||
|
||||
<Aside type="note">
|
||||
RAM readback may fail if the running firmware has disabled or overridden the `0xA0` vendor request. Stock Genpix firmware supports `0xA0` readback; some custom configurations may not. If you see consecutive read failures, the device firmware may need to be reloaded first.
|
||||
</Aside>
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Kernel Driver Conflict
|
||||
|
||||
The Linux `dvb_usb_gp8psk` module auto-loads when the SkyWalker-1 enumerates on USB. It will race with these tools for device access.
|
||||
|
||||
**Before using any tool**, either blacklist the module or unload it:
|
||||
|
||||
```bash title="Unload for current session"
|
||||
sudo modprobe -r dvb_usb_gp8psk gp8psk_fe
|
||||
```
|
||||
|
||||
```bash title="Permanent blacklist"
|
||||
echo -e "blacklist dvb_usb_gp8psk\nblacklist gp8psk_fe" | \
|
||||
sudo tee /etc/modprobe.d/blacklist-gp8psk.conf
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [EEPROM Utilities](/tools/eeprom-utilities/) -- for permanent firmware flashing
|
||||
- [Boot Sequence](/usb/boot-sequence/) -- what happens after firmware loads
|
||||
- [Custom Firmware v3.01.0](/firmware/custom-v301/) -- the open-source replacement firmware
|
||||
- [Vendor Commands](/usb/vendor-commands/) -- command reference used by these tools
|
||||
262
site/src/content/docs/tools/ts-analyzer.mdx
Normal file
262
site/src/content/docs/tools/ts-analyzer.mdx
Normal file
|
|
@ -0,0 +1,262 @@
|
|||
---
|
||||
title: TS Analyzer
|
||||
description: MPEG-2 Transport Stream analyzer for captured satellite data from the SkyWalker-1.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Steps, Aside, Badge } from '@astrojs/starlight/components';
|
||||
|
||||
`ts_analyze.py` parses and analyzes 188-byte MPEG-2 transport stream packets from `.ts` files captured by `tune.py`, piped from stdin, or any standard TS source. It covers PID distribution, PAT/PMT parsing, continuity counter verification, scrambling detection, bitrate estimation, and live stream monitoring.
|
||||
|
||||
Reference: ISO/IEC 13818-1 (MPEG-2 Systems).
|
||||
|
||||
## Subcommands
|
||||
|
||||
| Subcommand | Purpose |
|
||||
|------------|---------|
|
||||
| `analyze` | Full stream analysis with PID table, CC errors, bitrate (default) |
|
||||
| `pids` | Quick PID summary table |
|
||||
| `pat` | Parse and display the Program Association Table |
|
||||
| `pmt` | Parse and display Program Map Tables |
|
||||
| `dump` | Hex dump of individual TS packets |
|
||||
| `monitor` | Live stream monitoring with real-time statistics |
|
||||
|
||||
Passing a filename without a subcommand defaults to `analyze`.
|
||||
|
||||
## Global Options
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-v, --verbose` | Show sync search details and debug info |
|
||||
|
||||
---
|
||||
|
||||
## analyze -- Full Stream Analysis
|
||||
|
||||
Comprehensive analysis of a TS file or stream: total packets, unique PIDs, TEI errors, scrambling, continuity counter errors, PCR-based bitrate, and a per-PID distribution table.
|
||||
|
||||
```bash
|
||||
python3 tools/ts_analyze.py capture.ts
|
||||
```
|
||||
|
||||
```bash title="Analyze first 10000 packets only"
|
||||
python3 tools/ts_analyze.py analyze capture.ts --max-packets 10000
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `INPUT` | TS file path or `-` for stdin |
|
||||
| `--max-packets N` | Limit analysis to N packets (0 = all) |
|
||||
|
||||
**Example output:**
|
||||
|
||||
```
|
||||
MPEG-2 Transport Stream Analysis
|
||||
============================================================
|
||||
File: capture.ts (52,428,800 bytes)
|
||||
|
||||
Total packets: 278,876
|
||||
Total bytes: 52,428,688
|
||||
Unique PIDs: 12
|
||||
TEI errors: 0
|
||||
Scrambled: 0
|
||||
Duration: 5.23s (from PCR)
|
||||
Bitrate: 80.21 Mbps (PCR-based)
|
||||
|
||||
============================================================
|
||||
PID Distribution
|
||||
============================================================
|
||||
PID Count % CC Err Name
|
||||
--- ----- -- ------ ----
|
||||
0x0000 1,394 0.50% - PAT
|
||||
0x0001 278 0.10% - CAT
|
||||
0x0010 556 0.20% - NIT/ST
|
||||
0x0011 556 0.20% - SDT/BAT/ST
|
||||
0x0100 139,438 50.00% -
|
||||
0x0101 83,663 29.99% -
|
||||
0x0102 5,576 2.00% -
|
||||
0x1FFF 47,415 17.01% - Null
|
||||
```
|
||||
|
||||
### What It Detects
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| **PID count** | Packet count per Program ID |
|
||||
| **TEI** | Transport Error Indicator flag in the TS header |
|
||||
| **Scrambling** | Transport scrambling control bits (even/odd key) |
|
||||
| **CC errors** | Continuity counter discontinuities per PID |
|
||||
| **Bitrate** | Calculated from PCR timestamps when available |
|
||||
|
||||
---
|
||||
|
||||
## pids -- Quick PID Table
|
||||
|
||||
Faster variant of `analyze` that only counts packets per PID without CC checking or PCR extraction.
|
||||
|
||||
```bash
|
||||
python3 tools/ts_analyze.py pids capture.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## pat -- Program Association Table
|
||||
|
||||
Parses PID 0x0000 to extract the PAT, showing the transport stream ID and which PMT PID corresponds to each program number.
|
||||
|
||||
```bash
|
||||
python3 tools/ts_analyze.py pat capture.ts
|
||||
```
|
||||
|
||||
```
|
||||
Program Association Table (PAT)
|
||||
==================================================
|
||||
Transport Stream ID: 0x0001 (1)
|
||||
Version: 3
|
||||
Programs: 2
|
||||
|
||||
Program PMT PID Note
|
||||
------- ------- ----
|
||||
0 0x0010 NIT
|
||||
1 0x0100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## pmt -- Program Map Tables
|
||||
|
||||
Parses the PAT first to discover PMT PIDs, then parses each PMT to show the elementary streams (video, audio, data) in each program.
|
||||
|
||||
```bash
|
||||
python3 tools/ts_analyze.py pmt capture.ts
|
||||
```
|
||||
|
||||
```
|
||||
Program Map Tables
|
||||
============================================================
|
||||
Transport Stream ID: 0x0001
|
||||
|
||||
Program 1 (PMT PID 0x0100, version 2)
|
||||
PCR PID: 0x0101
|
||||
Streams:
|
||||
Type PID Description
|
||||
---- --- -----------
|
||||
0x02 0x0101 MPEG-2 Video (13818-2)
|
||||
0x04 0x0102 MPEG-2 Audio (13818-3)
|
||||
0x06 0x0103 PES Private Data
|
||||
```
|
||||
|
||||
### Known Stream Types
|
||||
|
||||
The tool recognizes these standard stream type identifiers:
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 0x01 | MPEG-1 Video |
|
||||
| 0x02 | MPEG-2 Video |
|
||||
| 0x03 | MPEG-1 Audio |
|
||||
| 0x04 | MPEG-2 Audio |
|
||||
| 0x06 | PES Private Data |
|
||||
| 0x0F | MPEG-2 AAC Audio |
|
||||
| 0x1B | H.264/AVC Video |
|
||||
| 0x24 | H.265/HEVC Video |
|
||||
| 0x81 | AC-3 Audio (ATSC) |
|
||||
|
||||
---
|
||||
|
||||
## dump -- Hex Dump Packets
|
||||
|
||||
Print detailed per-packet information including header fields, adaptation field flags, PCR values, and raw hex dump.
|
||||
|
||||
```bash title="Dump first 5 packets"
|
||||
python3 tools/ts_analyze.py dump capture.ts --count 5
|
||||
```
|
||||
|
||||
```bash title="Dump packets for a specific PID"
|
||||
python3 tools/ts_analyze.py dump capture.ts --pid 0x0100 --count 3
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--pid PID` | Filter by PID (hex `0x100` or decimal `256`) |
|
||||
| `--count N` | Maximum packets to dump (default: `10`) |
|
||||
|
||||
**Example output:**
|
||||
|
||||
```
|
||||
Packet #1
|
||||
PID: 0x0000 (PAT)
|
||||
TEI: 0 PUSI: 1 Priority: 0
|
||||
Scrambling: none Adaptation: payload only CC: 5
|
||||
Hex:
|
||||
0000: 47 40 00 15 00 00 B0 0D 00 01 C1 00 00 00 00 E0 G@..............
|
||||
0010: 10 00 01 E1 00 78 A0 B4 FF FF FF FF FF FF FF FF .....x..........
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## monitor -- Live Stream Monitoring
|
||||
|
||||
Real-time monitoring of a TS stream, reporting new PIDs as they appear, continuity errors, TEI errors, and bitrate.
|
||||
|
||||
```bash title="Monitor from a live stream pipe"
|
||||
sudo python3 tools/tune.py stream --stdout | python3 tools/ts_analyze.py monitor -
|
||||
```
|
||||
|
||||
```bash title="Monitor a growing file"
|
||||
python3 tools/ts_analyze.py monitor capture.ts
|
||||
```
|
||||
|
||||
The monitor prints events as they occur (new PIDs, errors) and updates a status line on stderr every second with running statistics.
|
||||
|
||||
```
|
||||
MPEG-2 TS Live Monitor
|
||||
============================================================
|
||||
Ctrl-C to stop
|
||||
|
||||
[ 0.0s] New PID: 0x0000 (PAT)
|
||||
[ 0.0s] New PID: 0x1FFF (Null)
|
||||
[ 0.1s] New PID: 0x0100
|
||||
[ 0.1s] New PID: 0x0101
|
||||
[ 0.2s] New PID: 0x0102
|
||||
278,876 pkts 52,428,688 bytes 80.21 Mbps PIDs: 12 CCerr:0 TEI:0 (5s)
|
||||
|
||||
Monitor Summary
|
||||
========================================
|
||||
Duration: 5.2s
|
||||
Packets: 278,876
|
||||
Bytes: 52,428,688
|
||||
Unique PIDs: 12
|
||||
CC errors: 0
|
||||
TEI errors: 0
|
||||
Avg bitrate: 80.21 Mbps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Capturing a Transport Stream
|
||||
|
||||
<Aside type="tip">
|
||||
To capture a TS stream for analysis, first tune to a transponder with `tune.py`, then capture with the `stream` subcommand:
|
||||
|
||||
```bash title="Tune and capture"
|
||||
sudo python3 tools/tune.py tune 12520 27500 --pol H --band high
|
||||
sudo python3 tools/tune.py stream -o capture.ts --duration 30
|
||||
```
|
||||
|
||||
```bash title="Pipe directly to analyzer"
|
||||
sudo python3 tools/tune.py stream --stdout | python3 tools/ts_analyze.py monitor -
|
||||
```
|
||||
</Aside>
|
||||
|
||||
## Sync Detection
|
||||
|
||||
The analyzer requires at least 3 consecutive sync bytes (`0x47`) at 188-byte intervals to confirm alignment. If the file starts with non-TS data (e.g., leading garbage from a partial USB transfer), the tool will skip ahead until sync is found.
|
||||
|
||||
When using `-v` (verbose), the sync search offset is reported. A non-zero sync offset may indicate that the capture started mid-packet or contains a non-TS preamble.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Tuning Tool](/tools/tuning/) -- capture TS data from a transponder
|
||||
- [GPIF Streaming](/bcm4500/gpif-streaming/) -- how TS data flows from BCM4500 through USB
|
||||
- [Vendor Commands](/usb/vendor-commands/) -- ARM_TRANSFER (0x85) starts/stops the stream
|
||||
293
site/src/content/docs/tools/tuning.mdx
Normal file
293
site/src/content/docs/tools/tuning.mdx
Normal file
|
|
@ -0,0 +1,293 @@
|
|||
---
|
||||
title: Tuning Tool
|
||||
description: DVB-S tuning, signal monitoring, LNB control, DiSEqC switching, and transport stream capture.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Steps, Aside, Badge } from '@astrojs/starlight/components';
|
||||
|
||||
`tune.py` is the primary user-facing tool for operating the SkyWalker-1 as a satellite receiver. It handles the complete signal chain: powering the demodulator, configuring LNB voltage and tone, sending DiSEqC switch commands, tuning to a transponder, monitoring signal quality, and capturing MPEG-2 transport stream data.
|
||||
|
||||
```bash
|
||||
pip install pyusb
|
||||
```
|
||||
|
||||
## Subcommands
|
||||
|
||||
| Subcommand | Purpose |
|
||||
|------------|---------|
|
||||
| `status` | Show device config, firmware version, and signal info |
|
||||
| `tune` | Tune to a transponder frequency |
|
||||
| `stream` | Capture MPEG-2 transport stream data |
|
||||
| `diseqc` | Send DiSEqC switch commands |
|
||||
| `lnb` | Control LNB voltage and 22 kHz tone |
|
||||
|
||||
Running with no subcommand defaults to `status`.
|
||||
|
||||
## Global Options
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-v, --verbose` | Show raw USB control transfer traffic |
|
||||
| `--json` | Output machine-readable JSON (where supported) |
|
||||
|
||||
---
|
||||
|
||||
## status -- Device Information
|
||||
|
||||
Displays the current device state: firmware version, configuration status flags, signal lock, and SNR.
|
||||
|
||||
```bash
|
||||
sudo python3 tools/tune.py status
|
||||
```
|
||||
|
||||
```
|
||||
Genpix SkyWalker-1 Status
|
||||
==================================================
|
||||
|
||||
USB: Bus 1 Addr 12 (VID 0x09C0, PID 0x0203)
|
||||
FW: 2.06.4 (built 2007-07-13)
|
||||
|
||||
Config: 0x07
|
||||
[ ON] 8PSK Started
|
||||
[ ON] BCM4500 FW Loaded
|
||||
[ ON] LNB Power On
|
||||
[off] DVB Mode
|
||||
[off] 22 kHz Tone
|
||||
[off] 18V Selected
|
||||
[off] DC Tuned
|
||||
[off] Armed (streaming)
|
||||
|
||||
Signal Lock: LOCKED
|
||||
SNR: 8.2 dB (raw 0x0823)
|
||||
Quality: [################------------------------] 42.3%
|
||||
```
|
||||
|
||||
Use `--json` for programmatic access to all fields.
|
||||
|
||||
---
|
||||
|
||||
## tune -- Transponder Tuning
|
||||
|
||||
The 8-step tuning sequence: check status, boot demodulator, enable LNB power, set voltage (polarization), set extra voltage, set 22 kHz tone (band), send TUNE_8PSK command, wait for signal lock.
|
||||
|
||||
### Required Arguments
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| `FREQ` | Transponder downlink frequency in MHz (e.g., `12520`) |
|
||||
| `SR` | Symbol rate in ksps (e.g., `27500`) |
|
||||
|
||||
### Options
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--pol H/V/L/R` | Polarization: H (horizontal/18V), V (vertical/13V), L (left circular/18V), R (right circular/13V) |
|
||||
| `--band low/high` | LNB band: low (tone off, 9750 MHz LO) or high (tone on, 10600 MHz LO) |
|
||||
| `--lnb-lo MHZ` | Override LNB local oscillator frequency (default: 9750 low, 10600 high) |
|
||||
| `--mod TYPE` | Modulation type (default: `qpsk`) |
|
||||
| `--fec RATE` | FEC rate (default: `auto`) |
|
||||
| `--timeout SECONDS` | Signal lock timeout (default: `10`) |
|
||||
| `--extra-volt` | Enable +1V LNB voltage boost for long cables |
|
||||
| `--json` | Output JSON result |
|
||||
|
||||
### Modulation Types
|
||||
|
||||
| Name | Description | FEC Group |
|
||||
|------|-------------|-----------|
|
||||
| `qpsk` | DVB-S QPSK | dvbs |
|
||||
| `turbo-qpsk` | Turbo-coded QPSK | turbo |
|
||||
| `turbo-8psk` | Turbo-coded 8PSK | turbo |
|
||||
| `turbo-16qam` | Turbo-coded 16QAM | turbo-16qam |
|
||||
| `dcii-combo` | Digicipher II Combo | dcii |
|
||||
| `dcii-i` | Digicipher II I-stream | dcii |
|
||||
| `dcii-q` | Digicipher II Q-stream | dcii |
|
||||
| `dcii-oqpsk` | Digicipher II Offset QPSK | dcii |
|
||||
| `dss` | DSS QPSK | dvbs |
|
||||
| `bpsk` | DVB BPSK | dvbs |
|
||||
|
||||
### FEC Rates by Group
|
||||
|
||||
| Group | Available Rates |
|
||||
|-------|----------------|
|
||||
| **dvbs** | `1/2`, `2/3`, `3/4`, `5/6`, `7/8`, `auto`, `none` |
|
||||
| **turbo** | `1/2`, `2/3`, `3/4`, `5/6`, `auto` |
|
||||
| **turbo-16qam** | `3/4`, `auto` |
|
||||
| **dcii** | `1/2`, `2/3`, `6/7`, `3/4`, `5/11`, `1/2+`, `2/3+`, `6/7+`, `3/4+`, `auto` |
|
||||
|
||||
<Tabs>
|
||||
<TabItem label="DVB-S">
|
||||
|
||||
```bash title="Standard DVB-S QPSK, Ku-band high"
|
||||
sudo python3 tools/tune.py tune 12520 27500 --pol H --band high
|
||||
```
|
||||
|
||||
```bash title="DVB-S with explicit FEC"
|
||||
sudo python3 tools/tune.py tune 11836 27500 --pol V --band low --fec 3/4
|
||||
```
|
||||
|
||||
```bash title="C-band with custom LNB LO"
|
||||
sudo python3 tools/tune.py tune 3960 26667 --pol V --lnb-lo 5150
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Turbo">
|
||||
|
||||
```bash title="Turbo 8PSK"
|
||||
sudo python3 tools/tune.py tune 12224 20000 --pol V --band high --mod turbo-8psk --fec 2/3
|
||||
```
|
||||
|
||||
```bash title="Turbo QPSK with auto FEC"
|
||||
sudo python3 tools/tune.py tune 12090 20000 --pol H --band high --mod turbo-qpsk
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="DCII">
|
||||
|
||||
```bash title="Digicipher II Combo"
|
||||
sudo python3 tools/tune.py tune 12224 20000 --pol V --band high --mod dcii-combo --fec auto
|
||||
```
|
||||
|
||||
```bash title="DCII Split I-stream"
|
||||
sudo python3 tools/tune.py tune 12224 20000 --pol V --band high --mod dcii-i --fec 6/7
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Tuning Output
|
||||
|
||||
```
|
||||
Tuning SkyWalker-1
|
||||
==================================================
|
||||
Downlink: 12520 MHz
|
||||
LNB LO: 10600 MHz
|
||||
IF Frequency: 1920.0 MHz (1920000 kHz)
|
||||
Symbol Rate: 27500 ksps (27500000 sps)
|
||||
Modulation: DVB-S QPSK (index 0)
|
||||
FEC: auto (index 5)
|
||||
Polarization: Horizontal (18V)
|
||||
Band: high (22kHz on)
|
||||
|
||||
[1/8] Config status: 0x07
|
||||
[2/8] Demodulator already running
|
||||
[3/8] LNB power already on
|
||||
[4/8] Setting LNB voltage: 18V
|
||||
[5/8] Extra voltage: off
|
||||
[6/8] 22 kHz tone: ON
|
||||
[7/8] Sending TUNE_8PSK...
|
||||
[8/8] Waiting for signal lock (timeout 10s)...
|
||||
...
|
||||
|
||||
LOCKED
|
||||
SNR: 8.2 dB (raw 0x0823)
|
||||
Quality: [################------------------------] 42.3%
|
||||
```
|
||||
|
||||
<Aside type="tip">
|
||||
The IF frequency is computed as `downlink - LNB_LO`. It must fall within 950--2150 MHz or the tool will warn. If you see negative IF values, your LNB LO is set higher than the downlink frequency -- check your LNB type.
|
||||
</Aside>
|
||||
|
||||
---
|
||||
|
||||
## stream -- Transport Stream Capture
|
||||
|
||||
Captures MPEG-2 transport stream data from EP2 bulk endpoint after the device is tuned and locked. Requires a prior successful `tune` command (signal must be locked).
|
||||
|
||||
```bash title="Capture to file for 60 seconds"
|
||||
sudo python3 tools/tune.py stream -o capture.ts --duration 60
|
||||
```
|
||||
|
||||
```bash title="Pipe directly to VLC"
|
||||
sudo python3 tools/tune.py stream --stdout | vlc -
|
||||
```
|
||||
|
||||
```bash title="Pipe to ffmpeg for recording"
|
||||
sudo python3 tools/tune.py stream --stdout | ffmpeg -i pipe: -c copy output.mp4
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `-o, --output FILE` | Write TS data to file |
|
||||
| `--stdout` | Write TS data to stdout (for piping) |
|
||||
| `--duration SECONDS` | Capture duration (default: until Ctrl-C) |
|
||||
|
||||
The stream status is written to stderr when using `--stdout`, so it does not contaminate the TS data pipe.
|
||||
|
||||
<Aside type="tip">
|
||||
Capture a short sample and analyze it with [ts_analyze.py](/tools/ts-analyzer/) to verify PIDs, check for continuity errors, and identify the programs in the transport stream.
|
||||
</Aside>
|
||||
|
||||
---
|
||||
|
||||
## diseqc -- Switch Commands
|
||||
|
||||
Send DiSEqC 1.0 port selection, mini-DiSEqC tone bursts, or raw DiSEqC messages.
|
||||
|
||||
```bash title="Select DiSEqC 1.0 port 1"
|
||||
sudo python3 tools/tune.py diseqc --port 1
|
||||
```
|
||||
|
||||
```bash title="Send tone burst A"
|
||||
sudo python3 tools/tune.py diseqc --tone-burst A
|
||||
```
|
||||
|
||||
```bash title="Send raw DiSEqC message"
|
||||
sudo python3 tools/tune.py diseqc --raw E0 10 38 F0
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--port 1-4` | DiSEqC 1.0 committed switch port |
|
||||
| `--tone-burst A/B` | Mini-DiSEqC tone burst |
|
||||
| `--raw HH HH ...` | Raw DiSEqC bytes in hex (3--6 bytes) |
|
||||
|
||||
For details on the DiSEqC signaling implementation, see [DiSEqC Protocol](/lnb-diseqc/diseqc-protocol/).
|
||||
|
||||
---
|
||||
|
||||
## lnb -- LNB Control
|
||||
|
||||
Direct control of LNB voltage, 22 kHz tone, and power supply. Running with no flags shows the current LNB state.
|
||||
|
||||
```bash title="Show LNB status"
|
||||
sudo python3 tools/tune.py lnb
|
||||
```
|
||||
|
||||
```bash title="Set voltage and tone"
|
||||
sudo python3 tools/tune.py lnb --voltage 18 --tone on
|
||||
```
|
||||
|
||||
```bash title="Power cycle the LNB"
|
||||
sudo python3 tools/tune.py lnb --power off
|
||||
sudo python3 tools/tune.py lnb --power on
|
||||
```
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--voltage 13/18` | LNB voltage (13V = vertical, 18V = horizontal) |
|
||||
| `--tone on/off` | 22 kHz tone (on = high band, off = low band) |
|
||||
| `--extra-volt` | Enable +1V boost (13V becomes 14V, 18V becomes 19V) |
|
||||
| `--power on/off` | LNB power supply on/off |
|
||||
|
||||
<Aside type="caution">
|
||||
The LNB can supply up to 750 mA non-continuous, but sustained loads should stay below 450 mA to avoid overheating the on-board regulator. Use `--extra-volt` only when needed for long cable runs.
|
||||
</Aside>
|
||||
|
||||
---
|
||||
|
||||
## Signal Quality Metrics
|
||||
|
||||
| Metric | Source | Description |
|
||||
|--------|--------|-------------|
|
||||
| **SNR** | `GET_SIGNAL_STRENGTH` (0x87) | Signal-to-noise ratio in dB, read as 16-bit value (dBu * 256 units) |
|
||||
| **Lock** | `GET_SIGNAL_LOCK` (0x90) | BCM4500 register 0xA4, bit 5 indicates signal lock |
|
||||
| **Quality %** | Computed | SNR scaled: `snr_raw * 17` maps to 0--100%, saturating at SNR >= `0x0F00` |
|
||||
|
||||
For details on the signal monitoring protocol, see [Signal Monitoring](/bcm4500/signal-monitoring/).
|
||||
|
||||
## See Also
|
||||
|
||||
- [Tuning Protocol](/bcm4500/tuning-protocol/) -- firmware-level TUNE_8PSK command format
|
||||
- [LNB Control](/lnb-diseqc/lnb-control/) -- hardware-level voltage and tone control
|
||||
- [TS Analyzer](/tools/ts-analyzer/) -- analyze captured transport streams
|
||||
- [Vendor Commands](/usb/vendor-commands/) -- complete USB command reference
|
||||
Loading…
Add table
Add a link
Reference in a new issue