SCK-2400 · Documentation · Developer Guide

SCK-2400 Developer Guide

SpaceCommsKit SCK-2400 Developer Guide

Version 1.14 — November 2026 SpaceCommsKit — https://spacecommskit.com/docs

This document covers the SCK-2400 development stack — from the CCSDS protocol foundation through the CC1352P firmware, OAD (Over-Air Download) system, and the CCSDS↔ESP payload bridge to the Raspberry Pi Pico payload board. If you are new to the system, read Section 1 before anything else.

The SCK-2400 shares its payload board architecture with the SCK-915. If you have read the SCK-915 Developer Guide, Section 4 (Payload Board Hardware Reference) will be familiar — the Pico firmware (main.py) is unchanged between the two products.


Quick Reference — Search Tags

Every cross-reference in the firmware source uses a [SCK-DEV: TAG] comment. Search for any tag in the codebase to jump directly to the relevant section:

Tag Topic Section
SCK-DEV: BOARD_ADDRESSING CCSDS APID board addressing 2.1
SCK-DEV: TX_POWER Bench vs field power modes 2.2
SCK-DEV: PAYLOAD_UART CC1352P↔Pico UART bridge 2.3
SCK-DEV: BIM_OAD Bootloader / OAD boot chain, golden image, trial boot, J4 recovery 2.4
SCK-DEV: ADD_COMMAND Adding new commands 3.1
SCK-DEV: OAD_STREAMING OAD Phase 3 streaming transport 3.2
SCK-DEV: CHUNKING Chunking large payload responses 3.3
SCK-DEV: ESP_FRAMING ESP framing on the payload UART 3.4
SCK-DEV: RESPONSE_FORMAT Pico response string conventions 3.5
SCK-DEV: BEACON Autonomous GPS beacon 3.6
SCK-DEV: SD_FLIGHT_LOG SD card flight log format 3.7
SCK-DEV: WATCHDOG Hardware watchdog timer — LEO fault recovery 3.8
SCK-DEV: CRYPTO AES-128-CCM RF encryption 3.9
SCK-DEV: NV_STORAGE Non-volatile reset counter / safe mode 3.10

1.0 System Overview

1.1 Architecture

Ground Station (Windows C#)
    ↕ USB — XDS110 — 921600 baud — CCSDS framing
SCK-2400 GS Board (CC1352P, APID 0x010)
    ↕ 2.4GHz RF — CCSDS framing
SCK-2400 Remote Board (CC1352P, APID 0x011)
    ↕ UART — 115200 baud — ESP framing
SCK-PBL-1 Payload Board (Raspberry Pi Pico)
    ├── OV2640 Camera    (SPI0 + I2C0)
    ├── MicroSD Card     (SPI0)
    ├── GPS NEO-6M       (UART1)
    └── BMP581/MS5611    (I2C1)

The GS board relays CCSDS commands transparently over RF to the remote board's APID. The remote board is a CCSDS↔ESP bridge — it speaks CCSDS on the RF side and ESP framing on the payload UART side, exactly mirroring the Pico's existing protocol from SCK-915.

Key architectural decision: the Pico's main.py requires zero changes from SCK-915. The CC1352P translates CCSDS commands into ESP frames the Pico already understands, and translates ESP responses back into CCSDS ACKs for the Ground Station. The Pico never knows whether it's talking to a CC1110 (SCK-915) or a CC1352P (SCK-2400).

1.2 Hardware Variants

Board Description Status
LAUNCHXL-CC1352P-2 ×2 TI LaunchPad — bringup validation platform Firmware validated here before custom PCB spin
SCK-2400 CC2652P1FRGZ, +20 dBm high-power TX, SCK-915 footprint — drop-in for existing 3D-printed stands and SCK-PBL-1 In production
SCK-PBL-1 Payload Pico + camera + GPS + altimeter + SD PCB Shared with SCK-915

The production SCK-2400 board and SCK-2400-M module run identical firmware to what's being bringup-tested in this guide — the CC1352P and CC2652P are pin/peripheral-compatible within the SimpleLink family, so the CCSDS dispatch, OAD transport, and payload bridge code carries forward unchanged. The SCK-2400 board is a form-and-fit drop-in replacement for SCK-915 — same mounting, same payload board connector, onboard power supply and conditioning, headers for power, UART, SPI and I2C — for development work and HAB/LEO missions. The SCK-2400-M module carries the same RF path with no power supply, bringing power in, UART0, UART1, SPI, I2C, JTAG (programming and debug, so no 2×5 header) and several spare GPIO out on castellated edge pads along its two long edges (module approx. 43.7 × 33.6 mm; exact per-pad pinout TBD), for soldering directly onto a customer's own board.

1.3 Firmware Components

File Language Runs On Purpose
main.c C CC1352P RTOS task creation, rfTask (RF + beacon + routing)
uart.c / uart.h C CC1352P CCSDS dispatch, payload UART bridge, OAD handlers
ccsds.h C CC1352P CCSDS packet structures and command opcodes
radio.c / radio.h C CC1352P RF driver wrapper (TX/RX, RX queue)
telemetry.c / .h C CC1352P Telemetry collection (uptime, RX/TX counters, VCC)
oad_*.c C CC1352P OAD ext-flash transport and image header
main.py MicroPython Pico Payload pipeline — unchanged from SCK-915

1.4 Repository Layout

sck2400_firmware/                ← CCS Theia project root
├── sck2400.syscfg               ← SysConfig — UART/SPI/RF pin assignments
├── main.c / main.h               ← RTOS tasks, rfTask
├── uart.c / uart.h                ← CCSDS dispatch + payload bridge
├── ccsds.h                       ← packet structs + command opcodes
├── radio.c / radio.h              ← RF driver wrapper
├── telemetry.c / telemetry.h      ← telemetry collection
├── oad_task.c / oad_task.h        ← OAD ext-flash session
├── oad_flash_stub.c               ← ext flash SPI (MX25R8035F)
├── oad_image_header_app.c         ← OAD image metadata (auto-patched by GS)
└── Debug/                         ← build output (sck2400_firmware.hex etc.)

Never hand-edit oad_image_header_app.c placeholder values. The Ground Station's build pipeline patches .prgEntry and .len automatically after each build. See Section 6.3.


2.0 Hardware Configuration Reference

2.1 CCSDS Board Addressing [SCK-DEV: BOARD_ADDRESSING]

The SCK-2400 reuses OpenLST-style board addressing, but encodes the board address in the CCSDS APID field instead of a separate HWID.

APID Role Notes
0x010 Ground Station board Connects via USB to the GS app, relays RF traffic
0x011 Remote 1 First remote/payload board
0x012 Remote 2 Second remote board (multi-board missions)
0x001 Telemetry beacon CCSDS_APID_TLM_BEACON — used for tlm_beacon responses
0x002 Legacy command path CCSDS_APID_COMMAND — generic command APID
0x003 Command ACK CCSDS_APID_CMD_ACK — all command responses

Each board's address is set at compile time via SCK_APID_THIS_BOARD in ccsds.h. The Ground Station's Firmware tab patches this value automatically based on the selected Board Role.

Routing logic (uart_dispatch_ccsds_packet in uart.c):

  • GS board + packet addressed to a remote APID → forward over RF via rf_forward_enqueue(), do not dispatch locally

  • GS board + packet addressed to 0x010 or CCSDS_APID_COMMAND → dispatch locally

  • Remote board + packet addressed to its own APID (pre-filtered by rfTask) → dispatch locally

  • Any board + unrecognized APID → discard silently

2.2 RF Power Modes [SCK-DEV: TX_POWER]

Power mode is set at flash time via TX_POWER in radio.h, patched automatically by the Ground Station's Firmware tab.

Mode TX_POWER Output Use Case
Bench BENCH (0 dBm) ~0 dBm Indoor/bench testing — default
Field MAX Full CC1352P output Field / HAB / LEO mission

Critical: There must be exactly one #define TX_POWER line in radio.h. The Ground Station's patching tool searches for this exact string — duplicating or relocating it breaks patching silently.

2.3 Payload UART — CC1352P↔Pico Bridge [SCK-DEV: PAYLOAD_UART]

The remote board bridges CCSDS (RF side) to ESP framing (Pico side) over a dedicated UART.

SysConfig UART2 instances (sck2400.syscfg):

Instance List Order / Index Peripheral TX Pin RX Pin Purpose
PAYLOAD_UART 0 (must be listed first) UART1 DIO13 DIO12 GS↔CC1352P — XDS110 backchannel
DEBUG_UART 1 UART0 DIO5 DIO16 CC1352P↔Pico payload bridge

Naming is historical and confusing — read carefully. Despite its name, PAYLOAD_UART is the Ground Station link (it was the original UART before the Pico bridge existed). DEBUG_UART is the one repurposed for the Pico payload link. Do not rename these in SysConfig — the Ground Station patching tool and uart.h defines assume these exact names and this exact list order.

uart.h configuration:

#define SCK_UART_IDX          0   /* PAYLOAD_UART — GS↔CC1352P (DIO12/13) */
#define SCK_PAYLOAD_UART_IDX  1   /* DEBUG_UART   — CC1352P↔Pico (DIO5/16) */
#define SCK_UART_BAUD         921600
#define SCK_PAYLOAD_UART_BAUD 115200  /* Matches Pico main.py */

LaunchPad → Pico wiring:

DIO5  (package pin 10) TX  →  Pico GPIO1 (UART0 RX, physical pin 2)
DIO16 (package pin 26) RX  ←  Pico GPIO0 (UART0 TX, physical pin 1)
GND                        →  Pico GND

CORRECTION (2026-07): an earlier revision of this guide listed DIO16 as "header pin 32." That was a units error — 32 was actually a LaunchPad BoosterPack connector position (SysConfig's boosterpack.32 notation), not a CC2652P package pin number. Confirmed directly against the CC2652P RGZ-48 datasheet pin diagram (Figure 6-1): DIO16 is package pin 26. DIO5 (package pin 10) was correct in both numbering systems, which is what made the DIO16 error easy to miss initially.

Both boards are 3.3V — no level shifter required.

2.3.1 Physical Connector Pinouts — SCK-2400 Production Board

UART0 header (Pico payload link, DEBUG_UART):

Pin Signal Net
1 GND GND
2 RX DIO16 (package pin 26)
3 TX DIO5 (package pin 10)
4 +3V3 +3V3

RTS/CTS pads exist on this header from the original layout but are not used by current firmware — uart_init() configures plain 8N1 with no flow control. Present in hardware for future use, not currently wired into the UART2 driver config.

J4 — UART1 header (Ground Station link, PAYLOAD_UART, ROM bootloader), 6-pin on production V3:

Pin Signal Net
1 GND GND
2 RX DIO12 (package pin 18)
3 TX DIO13 (package pin 19)
4 +3V3 +3V3
5 BACKDOOR DIO6 (package pin 11), 10kΩ pull-up to +3V3
6 RST RESET_N — added for production V3 (11/2026); 5-pin prototypes reset by power cycle

Layout correction (2026-07): this header was originally wired to package pins 10/11 (DIO5/DIO6) on the SCK-2400 — the LaunchPad's proven Pico-bridge pins, wired here by mistake. Corrected to DIO12(RX)/DIO13(TX), matching PAYLOAD_UART's actual SysConfig/ firmware definition. No firmware or SysConfig changes were needed — only the physical net assignment on this header.

Bootloader backdoor pin 5 added 2026-07. DIO6 (package pin 11) — freed up by the header correction above — was selected for the CCFG bootloader backdoor rather than reusing DIO16. CCFG settings: enableBootloader = true, enableBootloaderBackdoor = true, dioBootloaderBackdoor = 6, levelBootloaderBackdoor = "Active low". Requires an external 10kΩ pull-up to +3V3 on DIO6 (a static, low-speed sense pin — 10kΩ is appropriate; a lower value like 2.2kΩ is unneeded and just wastes current on a pin sampled only at reset). Moving the backdoor off DIO16 also reduces DIO16 to two roles (J2 debug connector + DEBUG_UART RX) instead of three — see Section 2.5 note on J2/DIO16 sharing.

Lazy initialization is mandatory. The payload UART is opened on first use via payload_uart_open(), never at boot:

static bool payload_uart_open(void)
{
    if (sPayloadUartHandle != NULL) return true;

    UART2_Params p;
    UART2_Params_init(&p);
    p.baudRate   = SCK_PAYLOAD_UART_BAUD;
    p.readMode   = UART2_Mode_NONBLOCKING;
    p.writeMode  = UART2_Mode_BLOCKING;
    sPayloadUartHandle = UART2_open(SCK_PAYLOAD_UART_IDX, &p);
    return (sPayloadUartHandle != NULL);
}

If the Pico is not connected, UART2_open on a floating RX line can block indefinitely if attempted at boot — opening lazily on the first payload command avoids this entirely. Also enable "Enable Nonblocking Mode" on DEBUG_UART in SysConfig — this allocates the RX ring buffer required for UART2_Mode_NONBLOCKING reads to return immediately when no data is available.

2.4 BIM / OAD Boot Chain, Golden Image and Recovery [SCK-DEV: BIM_OAD]

The SCK-2400 is designed so that a remote board cannot be bricked by a firmware update, including one sent to a board in orbit. Four layers each cover what the one before cannot:

LayerProtects againstWhere
1. Transfer CRC-16Lost or corrupted chunks during the RF transferApp, handle_oad_end()
2. Image CRC-32An image that went bad in external flash before installBIM, Bim_sckCrc32()
3. Trial boot + golden imageAn image that installs fine but crashes or can't talk to the groundBIM Bim_trialCheck() + app oad_trial_*()
4. ROM serial bootloader on J4No valid image left anywhere; wiped or corrupted internal flashCCFG (BIM build), chip ROM

The BIM itself is flashed once at provisioning and is never written by application builds or OAD.

SCK-2400 firmware update, failover and recovery flow An over-the-air update is verified twice, installed as a trial, and kept only if the board hears from the ground. After three unconfirmed boots the bootloader restores the golden image. If nothing valid remains, the ROM bootloader on J4 allows a full reflash. 1 · Ground station sends the update 128-byte chunks → external-flash candidate slot 2 · Received image CRC-16 matches? checked by the board at OAD END No Update refused Running firmware untouched; retry Yes 3 · Candidate marked ready OAD END ACK (status 0x00) · board resets 4 · BIM: image CRC-32 valid? computed over the copy in external flash No Not installed Board boots its current firmware Yes 5 · BIM installs and starts it copied to internal flash · trial boot 1 of 3 6 · Command from ground within 30 min? any valid command to this board confirms it Yes CONFIRMED Normal operation from here on Set Golden once you trust this build No — timeout, crash or watchdog 7 · Board resets BIM records another unconfirmed boot 8 · Three unconfirmed boots? counted in the candidate's metadata No — next trial boot Yes 9 · Candidate REJECTED BIM verifies the golden image CRC, then restores it to internal flash No golden image set? Nothing to revert to: the rejected image keeps running 10 · Board back on the golden image Flash Status: REJECTED · boots used 3 Last resort — no valid image anywhere The BIM never parks the chip in low-power mode: it waits about 10 s and resets, forever. Hold J4.5 (DIO6) low through a reset → the ROM bootloader starts on J4.2 / J4.3 (UART) → reflash the merged hex (BIM + app). Works even if internal flash is fully erased.

2.4.1 Flash Maps

Internal flash (CC2652P1F, 352 KB):

AddressContents
0x00000BIM (off-chip BIM, sck2400_bim project)
0x04000Application with OAD image header (oad_image_header_app.c). Max length 0x4E000
0x52000NVS (reset counter / safe mode, Section 3.10). Never part of an OAD image
0x57FA8CCFG (from the BIM build). BL_CONFIG at 0x57FD8

External flash (MX25R8035F, 1 MB, 4 KB pages) — layout since November 2026:

AddressContentsWritten by
0x000000 (page 0)Golden metadata (ExtImageInfo_t, counter = 0x444C4F47 "GOLD")CMD_OAD_SET_GOLDEN only
0x001000 (page 1)Candidate metadata (the image being updated)CMD_OAD_END; trial bits by the BIM and app
0x002000Candidate image (up to 0x4E000)CMD_OAD_CHUNK
0x080000Golden image (up to 0x4E000)CMD_OAD_SET_GOLDEN
0x0FE000, 0x0FF000Boot counter, two ping-pong pages (Section 3.9)boot_counter_next(), once per boot

Layout change. Before November 2026 the OAD metadata lived on page 0. That is TI's EFL_ADDR_META_FACT_IMG, so the BIM's "factory revert" only ever re-copied the last OAD image and there was no real fallback. handle_oad_start() erases a leftover non-GOLD page 0, so boards migrate on their first OAD. The BIM and the app must agree on this map (SCK_GOLDEN_MAGIC block in bim_offchip_main_local.c, OAD_* defines in uart.c).

2.4.2 Trial State Encoding

Trial state lives in the candidate metadata's 32-bit counter field. Flash bits can only be cleared without an erase, so each change is a single 1→0 write. No page erase happens during a boot.

FieldMeaning
counter = 0xFFFFFFFFWritten by CMD_OAD_END: fresh candidate, no boots used
Low byte, one bit cleared per bootBoots used = number of 0 bits. The BIM clears one before every jump to an unconfirmed candidate (the first boot after the copy counts as boot 1)
Top byte cleared (counter & 0xFF000000 == 0)Confirmed by the app (SCK_TRIAL_CONFIRM_MASK)
crcStat = CRC_INVALIDRejected by the BIM after SCK_TRIAL_MAX_BOOTS (3) boots

CMD_OAD_STATUS reports this as trialState: 0 none, 1 pending, 2 rejected, 3 confirmed, plus bootsUsed and goldenPresent.

2.4.3 BIM Decision Order

On every reset, Bim_checkImages() runs:

  1. Bim_trialCheck(): if the page-1 candidate is copied (COPY_DONE), not rejected and not confirmed, count the boots used. At 3 it marks the candidate CRC_INVALID and calls Bim_revertFactoryImage(). Otherwise it clears one more low-byte bit.
  2. checkImagesExtFlash(): a candidate marked NEED_COPY is checked with CRC-32 in external flash, copied to 0x4000, recorded as trial boot 1, and started.
  3. checkImagesIntFlash(): otherwise, boot the valid image already in internal flash.
  4. Bim_revertFactoryImage(): no valid internal image. This requires the GOLD marker on page 0 and a good CRC-32 of the golden image in external flash before internal flash is erased. A bad or missing golden image is never installed over a working one.
  5. Nothing valid: TI's BIM would park the chip in low-power mode forever. The SCK BIM waits about 10 s (CPUdelay) and calls SysCtrlSystemReset(), retrying forever. The ROM bootloader stays reachable on every reset.

2.4.4 Application Side

  • oad_trial_init(), called from rfTask after crypto init, reads both metadata pages to set sTrialState, sTrialBootsUsed and sGoldenPresent. If the running image is pending, it arms a one-shot Clock for SCK_TRIAL_TIMEOUT_S (default 1800 s) that calls SysCtrlSystemReset().
  • oad_trial_confirm() runs at the top of uart_dispatch_ccsds_packet() on the first valid command addressed to this board. That is over RF on a remote (viaRf), or over UART on the GS board. It clears the counter's top byte and stops the Clock. The Ground Station's post-OAD reboot poll (get_telem) therefore confirms a good image automatically.
  • Crashes and watchdog resets (Section 3.8) end a trial boot the same way the timeout does. Each one is a reset the BIM counts.

Worst-case fallback time = 3 × the time to the next reset. With the production timeout that is about 90 minutes for an image that runs but never hears the ground (about one LEO orbit). It is about 3–4 minutes for one that hangs (watchdog about 65 s, see L18). For bench tests, build with -DSCK_TRIAL_TIMEOUT_S=60, or edit the default in uart.c and put it back.

2.4.5 CMD_OAD_SET_GOLDEN (0x15)

Copies the running app (from 0x4000, length from its own header) byte-for-byte to 0x080000. It reads back and compares every page, yields between sectors for the watchdog, and writes the GOLD record on page 0 last, so an interrupted copy never looks valid. The copy is exact: the header's CRC-32 and crcStat are unchanged, so the BIM's CRC check on revert covers the same bytes. It takes about 7 s for a 312 KB image.

ACK: [0x15][status][err][4B len BE], status 0x00 = OK.

errMeaning
0x01OAD session active
0x02Running image still on trial — confirm it first
0x03Bad image length in the app header
0x04External flash open failed
0x05External flash erase failed
0x06External flash write failed
0x07Readback verify mismatch
0x08Golden record write failed

The golden image is in external flash, so it survives a J2 reflash (srfprog programs internal flash only).

2.4.6 Image CRC-32

The BIM checks images with CRC-32/IEEE (reflected polynomial 0xEDB88320, init and final XOR 0xFFFFFFFF, identical to zlib.crc32). It covers image bytes [12, len), skipping the image ID and the CRC field itself. After every build the Ground Station computes it (PatchSck2400ImageCrc32()) and writes it into the header at hex address 0x4008. The log shows Image CRC32 patched: 0x......... The BIM uses its own Bim_sckCrc32() because TI's CRC32_calc could not read external flash in this BIM build. Before November 2026 the field was left at 0xFFFFFFFF.

2.4.7 ROM Bootloader Recovery (J4)

The CC2652P has a serial bootloader in ROM that does not depend on anything in flash. The BIM's CCFG enables it with a backdoor pin:

/* sck2400_bim/ccfg_sck.c — replaces ccfg_app.c in the BIM project */
#define SET_CCFG_BL_CONFIG_BOOTLOADER_ENABLE  0xC5   /* enabled           */
#define SET_CCFG_BL_CONFIG_BL_LEVEL           0x0    /* active low        */
#define SET_CCFG_BL_CONFIG_BL_PIN_NUMBER      0x6    /* DIO6 = J4.5       */
#define SET_CCFG_BL_CONFIG_BL_ENABLE          0xC5   /* backdoor enabled  */
#include <ti/common/bim/ccfg_app.c>

Expected BL_CONFIG = 0xC5FE06C5. The flashed CCFG comes from the BIM, so check it on both the BIM hex and the merged hex before provisioning:

py check_ccfg.py V3\sck2400_bim.hex
py check_ccfg.py sck2400_merged.hex

build_bim_v3.bat compiles with -Werror=macro-redefined, so a project that still compiles TI's ccfg_app.c alongside ccfg_sck.c fails the build instead of shipping with the bootloader disabled (see L33).

J4 header (production V3, 1×6): 1 GND · 2 RX (DIO12) · 3 TX (DIO13) · 4 +3V3 · 5 BACKDOOR (DIO6, R40 pull-up) · 6 RST (RESET_N). The bootloader UART uses the same pins as PAYLOAD_UART, so a board's Ground Station link and its recovery port are the same connector.

Entering the bootloader: connect a 3.3 V USB-serial adapter (adapter TX → J4.2, RX → J4.3, GND → J4.1). Hold J4.5 low and reset the board, using J4.6 or a power cycle. The ROM samples DIO6 only at reset. If the flash has no valid image (for example after a mass erase), the ROM starts the bootloader without the backdoor.

Tool: cc2538_bsl.py (open source, pyserial; add intelhex for .hex input). It reports the chip as "CC1350 PG2.1 … 352KB Flash". That name comes from its chip table; the flash size and CCFG address are correct for the CC2652P1F.

# Read-only check (proven on V3 board #1, 11/09/2026): reads 4 KB, changes nothing
py .\cc2538_bsl.py -p COM6 -b 115200 -r -a 0 -l 4096 bim_readback.bin
py compare_readback.py bim_readback.bin V3\sck2400_bim.hex      # expect MATCH

# Full recovery (proven on V3 board #1, 11/10/2026): mass erase, write all
# 360,448 bytes (0x00000-0x57FFF: BIM + app + CCFG), verify by CRC-32. About 1 minute.
py -m pip install pyserial intelhex
py .\cc2538_bsl.py -p COM6 -b 115200 -e -w -v sck2400_merged.hex
#   Performing mass erase ... Erase done
#   Writing 360448 bytes starting at address 0x00000000 ... Write done
#   Verifying by comparing CRC32 calculations.  Verified (match: 0x........)

The Ground Station writes sck2400_merged.hex to the CCS workspace folder (for example C:\Users\<you>\workspace_ccstheia\) each time Flash is clicked. Run check_ccfg.py on it before writing it through the ROM bootloader.

Tool notes: the current file name uses an underscore (cc2538_bsl.py). A file argument is required even for a read. -a/-l take decimal. Without -e/-w nothing is changed. A J2 programmer on the board can hold the reset line, so unplug it first.

After recovery: remove the J4.5 jumper, reset, confirm Get Telem, then Set Golden Image again. The ROM bootloader only touches internal flash, so the old golden image and candidate records in external flash are still there. Setting golden again makes sure the fallback matches the recovered build.

2.4.8 Verification Procedure

Run this whenever the BIM, the flash map, the OAD code or the confirm rule changes. All four passed on SCK-2400 V3 board #1 on 11/09–11/10/2026.

TestStepsPass
1. BaselineFlash merged hex over J2; Flash StatusBoard answers; trial none
2. Set GoldenSet Golden Image; Flash StatusACK 0x00 in about 7 s; golden image: present
3. Good updateBuild same role (do not flash), Start OADEND 0x00; board answers about 10 s later; confirmed, boots 1
4. Bad updateBuild as a different APID with SCK_TRIAL_TIMEOUT_S 60, OAD it to the board's real APID, send nothing to the new APID3 resets about 1 min apart, then the board answers at its real APID: REJECTED, boots 3, golden present

A build for another APID never sees a command addressed to it, so it never confirms. That gives a reproducible "update that can't talk to the ground" without writing a deliberately broken image. After Test 4, put the timeout back to 1800 s, OAD a clean build, and Set Golden.

2.4.9 Design Limits

  • Confirmation proves the link, not the build. An image that answers commands but has another bug is confirmed and kept. Roll it back with an OAD of the previous build. There is no "revert to golden" command yet.
  • No golden image means no automatic fallback. The rejected image keeps running. Set Golden is a provisioning step.
  • The golden image is only as good as the build you set. Only set firmware that has been tested on that board.
  • The BIM is not field-updatable by design. A BIM change requires J2 or J4.

2.5 Programming / Debug Connector (J2)

The SCK-2400 carries a 2×5 (10-pin), 0.05" pitch programming/debug header (J2), matching the standard TI LaunchPad XDS110 debug-out pinout used on LAUNCHXL-CC1352P-2 boards. It allows an external XDS110 (including a LaunchPad's onboard XDS110 in pass-through mode) to program/debug boards that don't carry their own onboard debug probe.

This is not a JTAG connector, despite two of its signal labels (TCKC, TMSC) being inherited from the CC1352P pin-naming in TI's pinout tool. Those names describe SWD-capable pins on the die, not a JTAG-standard header pinout. Refer to J2 as the Programming/Debug connector or XDS110 debug header in documentation and silkscreen — not "JTAG."

Pin Signal
1 U1-Reset_N
2 GND
3 U1-DIO_17
4 GND
5 U1-DIO_16
6 +3V3
7 U1-JTAG_TCKC
8 GND
9 U1-JTAG_TMSC
10 +3V3

A standard 10-pin ribbon cable from any LaunchPad's debug-out header plugs directly into J2 for external programming/debug.

DIO16 sharing note (2026-07): J2 pin 5 (DIO_16) is also DEBUG_UART RX — the Pico payload link (see Section 2.3.1). This is intentional, not a conflict: J2 is used during development/programming sessions, while the Pico is the operational payload processor — the two are not normally live at the same time. Operational rule: do not have a debug probe connected to J2 while the Pico is also connected on the UART0 payload header, since both would drive DIO16 simultaneously.


2.6 Hand Assembly of the QFN Parts

Boards built by hand, with a hand-printed stencil, need QFN edge pads that are longer and wider than the minimum land patterns many part libraries ship. With minimum pads, a slightly thin paste print leaves a cold or open joint even when placement is perfect. That is what caused two of the first SCK-2400 V3 failures in November 2026. Since then all SpaceCommsKit boards use the pads below.

PartPackageEdge pad (mm)Pad span from chip centrePast the body edgePaste per padPrevious pad
CC2652P (SCK-2400 V3, SCK-2400-M)VQFN-48, 7 × 7 mm, 0.5 mm pitch0.28 × 0.803.00–3.80 mm0.30 mm0.224 mm²0.24 × 0.60 (0.144 mm²)
CC1110 (SCK-915)QFN-36, 6 × 6 mm, 0.5 mm pitch0.28 × 0.9952.405–3.40 mm0.40 mm0.279 mm²0.28 × 0.75 (0.210 mm²)
CC1190 (SCK-915)QFN-16, 4 × 4 mm, 0.65 mm pitch1.00 × 0.351.72–2.72 mm0.72 mm—Unchanged (TI reference pattern)

For comparison, TI's LAUNCHXL-CC1352P uses 0.30 × 0.90 mm edge pads (3.00–3.90 mm from the chip centre) with 1:1 paste. The SCK-2400 pads stop slightly short of that so the existing fan-out traces keep their 0.127 mm clearance. On a new layout, use TI's size.

  • Extend pads outward, not inward. A longer outer end adds paste, gives a visible toe fillet for inspection, and leaves room for a soldering iron. Extending toward the centre pad only adds bridging risk.
  • Let the pads make their own solder-mask openings. Don't draw extra F.Mask openings around a QFN. Hand-drawn openings on the first V3 layout came within 0.01 mm of neighbouring traces and left bare trace past each pad end, which pulls solder away from the joint.
  • Centre pad. The CC2652P footprint uses 16 paste windows (about 68% of the 5.15 mm pad) with the thermal vias in the gaps between them. The CC1110 footprint deliberately uses only 16 small paste dots (about 10%). Both keep the chip from floating on the centre pad, which would lift the edge pins off their pads.

Stencil and printing

  • Stencil 0.12–0.13 mm (5 mil), electropolished or nano-coated if possible. Edge-pad apertures 1:1 with the pads.
  • Type 4 paste for 0.5 mm pitch. Let it reach room temperature and stir it before use.
  • Hold the board in a jig with the stencil on alignment pins. Use a metal squeegee, one pass at about 45° with firm, even pressure, then lift the stencil straight up.
  • Inspect every QFN edge pad under magnification before placing parts. If any deposit is thin, wipe the board and print again.
  • Reflow: about 60–90 s above liquidus, peak about 240 °C for SAC305.

Inspection before first power

  1. Inspect all four sides of each QFN under magnification for a fillet at every pad end.
  2. Diode check: board unpowered, meter in diode mode, red lead on GND, black lead on each signal pin's trace (at a via, pad or header pin). A good joint reads about 0.5–0.7 V through the chip's internal protection diode. A cold or open joint reads OL. Compare against a known-good board. Check at least the debug pins (J2), the RF pins and the UART pins.
  3. Optional touch-up: flux along each side and touch each pad end with a fine iron tip.

Symptoms of a QFN joint fault on a new board. "Debug interface is locked" on a factory-new CC2652P means a marginal JTAG_TMSC or JTAG_TCKC joint (chip pins 24/25), not a locked chip. Reflow those pins before trying a mass erase or the ROM bootloader. A board that boots (D1 flashes three times) but never answers over RF points to a joint in the RF path.


3.0 Firmware Extension Reference

3.1 Adding New Commands [SCK-DEV: ADD_COMMAND]

Adding a new command requires changes in up to four places.

Step 1 — Assign a CCSDS opcode in ccsds.h

/* Payload board commands occupy 0x20-0x29.

 * General commands occupy 0x01-0x04, OAD occupies 0x10-0x14.
 * Pick the next free opcode in the appropriate range. */
#define CMD_MY_COMMAND  0x2A

Step 2 — Add a case in uart_dispatch_ccsds_packet() (uart.c)

For a payload board command (forwards to the Pico), use the generic bridge helper:

case CMD_MY_COMMAND:
    handle_pico_cmd(seqCount, /* picoSub */ 0x0A,
                    dataField + 1, (uint8_t)(dataFieldLen - 1),
                    CMD_MY_COMMAND, /* respMax */ 64);
    break;

For a board-local command (no Pico involved), write a dedicated handler following the pattern of handle_get_telem() or handle_cmd_ack().

Step 3 — Add the matching sub-opcode to Pico main.py

CMD_MY_COMMAND = 0x0A   # Next available ESP sub-opcode

# In the main command dispatch loop:
elif sub_opcode == CMD_MY_COMMAND:
    try:
        result = do_something(payload[1:])
        msg = f"MYRESP:{result}"
        send_esp(msg.encode())
        blink(1)
    except Exception as e:
        send_esp(b"MYRESP:ERR:FAIL")

If the response may exceed the static buffer size used by handle_pico_cmd() (220 bytes), implement chunking — see Section 3.3.

Step 4 — Add to the C# Ground Station

// In CcsdsProtocol.cs — add the opcode constant
public const byte CMD_MY_COMMAND = 0x2A;

// In CustomCommand.cs Defaults() — add a pre-loaded entry
new CustomCommand { Name = "My Command", Opcode = 0x2A, Payload = "",
                     Notes = "Description — expects MYRESP:..." },

SendCustomCommandAsync() already handles SCK-2400 CCSDS framing — no further GS changes needed for a simple request/response command.

Critical rules

Rule Consequence if violated
handle_pico_cmd() buffers must stay static Stack overflow — uart_task crashes silently (see L6)
SCK_TASK_STACK_UART must be ≥2048 Payload command call chain overflows a 512-byte stack
Never call payload_uart_open() at boot Floating RX line can block UART2_open indefinitely
One opcode = one CCSDS sub-opcode Do not reuse 0x20 with different payload bytes — each command needs its own CCSDS opcode (see L4)
ccsds.h opcode defines must be in sync across firmware AND GS Mismatched/undefined opcodes compile silently with wrong values

3.2 OAD Streaming Transport [SCK-DEV: OAD_STREAMING]

OAD (Over-Air Download) transfers a complete firmware image to a remote board over RF in three phases.

Performance (312 KB image, SCK-2400 V3, encrypted RF via the GS board, measured 11/2026):

Mode Time Throughput % of 8-min LEO pass
Streaming, 128-byte chunks, 30 ms delay (default) 84.6–85.9 s 3.8 KB/s 18%

Earlier editions quoted 24 s with 240-byte chunks at 10 ms. That figure predates RF encryption: a 240-byte chunk with its CCSDS header and command fields is 252 bytes before encryption, and the 21-byte nonce and MAC push it past the 255-byte RF packet limit. The chunk size is now 128 bytes in both the firmware and the Ground Station (see L1). Faster settings are a future optimisation and must be re-verified against Section 2.4.8.

Phase 1 — CMD_OAD_START (0x10)

Payload: [4B imgSize BE][2B crc16 BE]

Remote board:

  1. Opens ext flash (extFlashOpen())
  2. Rejects imgSize of 0 or over 0x4E000; erases a leftover non-GOLD page 0 (legacy layout); then erases the candidate slot — OAD_SLOT_OFFSET (page 1, 0x1000) through OAD_IMG_OFFSET + imgSize, rounded to a 4 KB sector. Page 0 and the golden image are never touched (Section 2.4.1)

  3. Initializes session state, sets gOadActive = true

  4. Leaves flash open for the duration of the session — closing and reopening on every chunk triggers Deep Power-Down cycling at 50Hz, which is unreliable (see L7)

ACK payload: [subOp][status][flashErrCode][manfId][devId]

Phase 2 — CMD_OAD_CHUNK (0x11), streamed

Payload: [4B offset BE][1B chunkLen][chunkData...]

Streaming mode — no per-chunk ACK. The Ground Station sends all chunks back-to-back at the configured inter-chunk delay (30 ms default). The remote board writes each chunk to OAD_IMG_OFFSET + offset (0x2000 + offset) and returns immediately — no response.

OAD_CHUNK_SIZE = 128 bytes. This must match the Ground Station's CHUNK_SIZE exactly — a larger GS chunk fails the chunkLen > OAD_CHUNK_SIZE check on every chunk (see L1).

GS board forwarding: chunks reach the remote through the GS board, which normally holds a 1500 ms reply window after each RF forward. OAD chunks are forwarded with rf_forward_enqueue_ex(buf, len, false) (no reply window), and the GS loop sleeps 2 ms instead of the beacon interval while the GS beacon is off. Without this the GS board drops almost every chunk (L31).

gOadActive and the rfTask sleep: during OAD, rfTask must drain the RX queue fast enough to keep up with incoming chunks (~100Hz at 10ms). The RX queue holds only 4 entries.

/* main.c — rfTask main loop, remote board only */
#if !SCK_IS_GS_BOARD
usleep(gOadActive ? 1000 : SCK_BEACON_REST_US);
#else
usleep(SCK_BEACON_REST_US);
#endif

Without this, the 950ms beacon sleep causes the RX queue to overflow and chunks are silently dropped (see L2).

Diagnostic NACK (only sent on error):

[CMD_OAD_CHUNK][0x01][flashErrCode][4B offset BE]

Phase 3 — CMD_OAD_END (0x12)

Payload: [4B crc32 BE]  (legacy field — actual verification uses CRC16)

Remote board:

  1. Verifies bytesReceived == imgSize
  2. Reads back the full image from ext flash and computes CRC16
  3. If CRC matches, writes ExtImageInfo_t candidate metadata to page 1 (0x1000) with imgCpStat = NEED_COPY and counter = 0xFFFFFFFF (trial not started, Section 2.4.2)

  4. Closes ext flash, sends ACK [CMD_OAD_END][status]

  5. Task_sleep(200) then SysCtrlSystemReset()

The 200ms delay lets the ACK transmit before reset. The Ground Station's oad_end wait timeout is 8000 + (imgSize/1024) * 50 ms — for 335KB this is ~24.4s. If no ACK arrives within this window (the board may have already reset), the Ground Station treats this as success and waits for the board to reboot and resume beaconing.

CMD_OAD_ABORT (0x13) and CMD_OAD_STATUS (0x14)

Abort clears session state and closes ext flash with no further action. Status returns 13 bytes: [0x14][1B active][4B bytesReceived][4B imgSize][1B trialState][1B bootsUsed][1B goldenPresent]. The last three bytes were added in November 2026 (Section 2.4.2). Older GS builds read only the first six.

CMD_OAD_SET_GOLDEN (0x15)

No payload. Copies the running image to the golden slot — see Section 2.4.5 for the procedure and error codes.


3.3 Chunking Large Payload Responses [SCK-DEV: CHUNKING]

The CCSDS↔ESP bridge (handle_pico_cmd) uses static 220/222-byte buffers. Responses from the Pico larger than this — e.g. LIST: with many files — are truncated at the buffer boundary in the current implementation.

For responses that must exceed this limit, follow the SCK-915 chunking pattern in main.py (unchanged):

# "LIST:" prefix = first chunk, "LIST+:" = continuation
# Final chunk has NO trailing comma — signals end of list
CHUNK = MAX_PAYLOAD - 8
# ... build and send_esp() each chunk ...

Ground Station reassembly for SCK-2400 chunked responses is not yet implemented — this is a known gap for the Files tab when listing SD cards with many files. See Section 7, item pending.


3.4 ESP Framing on the Payload UART [SCK-DEV: ESP_FRAMING]

Identical to SCK-915 — the Pico's send_esp() / recv_esp() are unchanged.

[0x22][0x69][length][payload bytes...]
  ↑      ↑      ↑         ↑
Start  Start  1 byte   1-251 bytes
byte0  byte1  payload  command data
              length

CC1352P-side implementation (pico_send_recv in uart.c):

#define PICO_ESP_BYTE0   0x22
#define PICO_ESP_BYTE1   0x69
#define PICO_TIMEOUT_MS  5000

/* Send: [0x22][0x69][1+argsLen][subOpcode][args...] */
/* Receive: poll UART2_read() non-blocking, 1ms sleep between polls,

 * state machine: sync0 → sync1 → length → payload */

Critical: unlike the SCK-915 CC1110 implementation (interrupt-driven UART), the CC1352P implementation here uses a polling loop with usleep(1000) between non-blocking read attempts. This works correctly but ties up uart_task for up to PICO_TIMEOUT_MS (5 seconds) per payload command. Other CCSDS commands queued during this window will wait. This is acceptable for the current command set but should be revisited if low-latency commands need to interleave with payload commands.


3.5 Pico Response String Conventions [SCK-DEV: RESPONSE_FORMAT]

Unchanged from SCK-915 — PREFIX:field1,field2,.... The CCSDS↔ESP bridge maps each CCSDS opcode to a Pico ESP sub-opcode by the pattern CCSDS 0x2N → ESP 0x0N:

CCSDS Opcode Pico ESP Sub-opcode Success Response
CMD_PICO_PING (0x20) 0x00 PICO:ACK
CMD_PICO_TEMP (0x21) 0x01 TEMP:23.45C
CMD_PICO_SNAP (0x22) 0x02 SNAP:OK:snap_001.jpg:24576
CMD_PICO_LIST (0x23) 0x03 LIST:file1.jpg,file2.jpg
CMD_PICO_INFO (0x24) 0x04 INFO:snap_001.jpg:24576:123
CMD_PICO_CHUNK (0x25) 0x05 CHUNK:0:<200 bytes>
CMD_PICO_DELETE (0x26) 0x06 DEL:OK:snap_001.jpg
CMD_GET_GPS (0x27) 0x07 GPS:lat,lon,gps_alt,sats,fix,hpa,baro_alt,temp_c
CMD_GET_BARO (0x28) 0x08 BARO:hpa,baro_alt,temp_c
CMD_PICO_BEACON (0x29) 0x09 BEACON:ON / BEACON:OFF

All responses are wrapped in a CCSDS cmd_ack (APID 0x003) by handle_pico_cmd(): [ccsdsCmd][status][response bytes...].


3.6 Autonomous GPS Beacon [SCK-DEV: BEACON]

Unchanged from SCK-915 — the Pico transmits a fused GPS+baro packet every 10 seconds (GPS_BEACON_INTERVAL_MS = 10000) when enabled and idle.

Controlling the beacon from SCK-2400:

CMD_PICO_BEACON (0x29) + payload 0x01 → ESP 0x09 + 0x01 → enable
CMD_PICO_BEACON (0x29) + payload 0x00 → ESP 0x09 + 0x00 → disable

Race condition: because the bridge UART (Section 3.4) polls with a 5-second timeout, an autonomous beacon transmitted by the Pico during this window can be captured by pico_send_recv() instead of the intended command response — the Ground Station will then display the beacon's GPS:... string instead of the expected response (e.g. TEMP:...). Always send CMD_PICO_BEACON OFF before running command sequences, and CMD_PICO_BEACON ON afterward if continuous beaconing is desired.

Every beacon packet is also written to the SD flight log — see 3.7.


3.7 SD Card Flight Log Format [SCK-DEV: SD_FLIGHT_LOG]

Unchanged from SCK-915. One .sckflight JSON file per power cycle, FLT-001.sckflight, FLT-002.sckflight, etc. See the SCK-915 Developer Guide Section 3.7 for the full format and field-addition instructions — write_flight_packet() in main.py is identical.


3.8 Watchdog Timer — LEO Fault Recovery [SCK-DEV: WATCHDOG]

The CC1352P hardware watchdog resets the board if any task deadlocks or spins without yielding. This is the primary fault recovery mechanism for LEO missions where hands-on recovery is impossible.

Architecture:

rfTask       (priority 2) ─┐
uartTask     (priority 2) ─┤── if any spin → watchdogTask starved
watchdogTask (priority 1) ─┘   → WDT expires → CC1352P reset (~65s)

watchdogTask runs at the lowest RTOS priority (1). Starvation IS the detection mechanism — no explicit hang detection is required.

SysConfig (sck2400.syscfg): Add CONFIG_WATCHDOG_0 under TI Drivers → Watchdog. Period: 30000 ms. Peripheral: Any(WDT0).

Implementation (main.c):

// In mainThread() after SPI_init():
Watchdog_init();

void watchdogTask(UArg a0, UArg a1)
{
    Watchdog_Params p;
    Watchdog_Params_init(&p);
    p.resetMode     = Watchdog_RESET_ON;
    p.debugStallMode = Watchdog_DEBUG_STALL_ON;
    Watchdog_Handle h = Watchdog_open(CONFIG_WATCHDOG_0, &p);

    // CRITICAL: CC1352P watchdog stops in standby without this.
    Power_setConstraint(PowerCC26XX_DISALLOW_STANDBY);

    while (1)
    {
        Watchdog_clear(h);   // kick every 10s within 30s window
        Task_sleep(10000);    // yields — starvation is the detection
    }
}

CC1352P two-timeout reset: The CC1352P fires an NMI on the first timeout and only resets on the second timeout with the flag still pending. Total time from hang to reset is ~65 seconds at a 30-second period — factor this into test timing.

Debug stall: With Watchdog_DEBUG_STALL_ON, any JTAG connection (including a background CCS connection) pauses the watchdog hardware. Disconnect JTAG after flashing for watchdog testing.

Verified: uart_task deliberate spin → LED went dark (watchdogTask starved) → board reset at ~65s → post-reset get_telem nominal. ✓

Configuration summary:

Parameter Value
Timeout 30,000 ms (30 seconds)
Kick interval 10,000 ms via Task_sleep(10000)
Reset mode Watchdog_RESET_ON
Debug stall Watchdog_DEBUG_STALL_ON
Power constraint PowerCC26XX_DISALLOW_STANDBY
Task priority 1 (lowest)
Task stack 512 bytes

3.9 RF Encryption (AES-128-CCM) [SCK-DEV: CRYPTO]

All RF communication uses AES-128-CCM per-packet encryption and authentication. Implementation is in crypto.c — pure C, RFC 3610, no TI hardware accelerator.

Why software AES: The TI AESCCM hardware driver cannot be safely called from rfTask context (semaphore poisoning) and produces different keystream than .NET AesCcm. Software AES is task-context safe and matches .NET exactly.

Wire format:

[CCSDS Header 6B][Nonce 13B][Encrypted Payload N bytes][MAC 8B]

CCM parameters:

Parameter Value
Algorithm AES-128-CCM (RFC 3610)
Key length 16 bytes
Nonce length 13 bytes: sender APID, boot count, message counter (see below)
MAC length 8 bytes
Keys per pair 3 (Option A fallback)
Overhead 21 bytes per packet

Key provisioning: Three keys per board pair. Generated in the Ground Station Provision tab (🎲 Roll). Automatically patched into security.h before each build. security.h is gitignored — never committed.

Self-test on every boot: crypto_init() verifies a known test vector. 6 fast LED blinks if it fails. The board continues but crypto is broken.

Known test vector:

Key: 0xFF×16  Nonce: 0x00×11+0xC0+0x07  AAD: 18 11 C0 07 00 15
Plaintext: 0x01  →  Ciphertext: 0x83  MAC: 85 84 6C 8D 8C 2A 0B 19

Task context: crypto_decrypt() and crypto_encrypt() are safe to call from rfTask — pure C, no hardware dependencies. On a remote, decrypt → dispatch → encrypt all happen in rfTask. On the GS board, uplink encryption runs in uart_task and downlink decryption in rfTask; each owns its own state (message counter vs replay table), so they never write the same data.

3.9.1 Nonce (since November 2026)

byte  0-1   sender APID (SCK_APID_THIS_BOARD of the board that encrypted it)
byte  2-5   boot count   (big-endian, +1 every boot, external flash)
byte  6-9   message counter (big-endian, +1 every encrypted packet this boot)
byte  10    nonce format version = 0x01
byte 11-12  CCSDS sequence word (informational only)

AES-CCM must never reuse a nonce with the same key. Sender + boot count + counter is unique for the life of a board, so neither a reboot nor a restart of the Ground Station app can repeat one. The whole nonce is authenticated (it is part of CCM block B0), so a forged sender or counter fails the MAC. Packet size is unchanged: the nonce was already 13 bytes.

Old and new firmware cannot talk. Packets whose byte 10 is not 0x01 (everything built before November 2026) are rejected. Update the GS board and every remote together, over J2. A remote whose golden image predates the change must get a new golden image (Set Golden) before it relies on rollback.

3.9.2 Replay protection

Each board keeps a small RAM table (4 senders) of the highest (boot count, message counter) it has authenticated from each sender APID. A packet is accepted only if its pair is newer. The table is updated only after the MAC verifies, and a reboot of the receiver clears it, which is safe because every peer's counters only move forward.

Boot counter (boot_counter.c): two 4 KB pages at the top of external flash, 512 slots of {count, ~count} each. One slot is programmed per boot (no erase); a page is erased once every 1024 boots. A slot counts only if the second word is the exact complement of the first, so a write cut short by a power loss or a half-erased page can't produce a bogus count. External flash isn't touched by J2 or J4 reflashing, so the count survives recovery. If external flash fails, the boot count is 0 and the board still runs.

3.9.3 Lockout recovery

A receiver rejects a peer whose boot count went backwards (its external flash was erased or replaced). Two ways back:

MechanismHowNotes
CMD_CRYPTO_RESET_REPLAY (0x16)Clears the replay table of the board that receives itLocal cable only (USB on the GS board, J4 on a remote). Over RF it is refused with 16 E1
Silence timeoutAfter SCK_CRYPTO_SILENCE_RESET_S (6 h) with no authenticated packet, the table clears itselfGuarantees a remote in orbit can always be reached again. Trade-off: after a long silence, one old recorded packet could be replayed once

3.9.4 Diagnostics

CMD_CRYPTO_STATUS (0x17, allowed over RF) returns, big-endian:

[0x17][accepted 4B][rejMac 4B][rejReplay 4B][rejFormat 4B]
      [replayClears 4B][silenceResets 4B][bootCount 4B]

0x16 returns the same block after [0x16][status]. A clear requested by 0x16 takes effect at the next decrypted packet, so the reply still shows the old replayClears. A GS board that drops a remote's replies used to do so silently; send 0x17 to 0x010 and the reject counters say why (MAC, replay or format).

3.9.5 Verification (passed on V3 board #1 and the GS LaunchPad, 11/10/2026)

TestPass
0x17 to the GS board, power-cycle, 0x17 againBoot count goes 1 → 2
Get Telem to the remote, then close and reopen the GS app, Get Telem againStill answers (the pre-fix firmware dropped every reply here)
Power-cycle the remote, then the GS board; Get Telem after eachAnswers both times
0x17 to the remote over RFrejReplay 0, boot count matches its boots
0x16 to 0x010 / to the remote over RF16 00 … / 16 E1
OAD to the remote, Flash Status, Set GoldenAbout 85 s, confirmed, golden set

Keys. The Provision tab's default keys are FF… placeholders, and the build log says so. Roll real keys, back them up outside the app folder, and rebuild every board with them before anything flies or ships. Both ends must use the same key set.


3.10 Non-Volatile Storage — Reset Counter and Safe Mode [SCK-DEV: NV_STORAGE]

Non-volatile reset counter in internal flash at 0x52000 (8KB, pages 82-83). Five consecutive non-power-on resets without a 5-minute clean run triggers safe mode (beacon only).

Flash layout:

0x00000–0x03FFF  BIM (pages 0-3)
0x04000–0x51FFF  Application (0x4E000 bytes)
0x52000–0x53FFF  NVS region (pages 82-83, 8KB)  ← reset counter lives here
0x54000–0x55FFF  Reserved
0x56000–0x57FFF  CCFG

Why direct flash (not TI NVS driver): NVS_write() returns success and NVS_WRITE_POST_VERIFY passes (reading from write buffer), but data does not survive reset. Fix: FlashSectorErase() + FlashProgram() + FlashCheckFsmForReady() polling + Power_setConstraint(PowerCC26XX_DISALLOW_STANDBY)

  • VIMS cache disable around all flash operations.

Deferred write: nv_storage_on_boot() is called from watchdogTask after a 10-second Task_sleep(). Use Task_sleep() not usleep() — usleep() busy-spins on TI-RTOS7 and causes the clean-run timer to fire immediately, resetting the counter to 0.

Reset cause gating: NVS operations run on SYSRESET, WARMRESET, and PIN. Power-on is excluded to avoid NVS hangs on cold start. On the LaunchPad, CMD_REBOOT asserts RSTSRC_PIN_RESET (not SYSRESET).

Bench caveat: XDS110 debugger erases NVS on every software reset. Test NVS persistence with real power cycles (unplug/replug) on the bench.


4.0 Payload Board Hardware Reference

The SCK-PBL-1 payload board (Pico + camera + GPS + altimeter + SD) is shared between SCK-915 and SCK-2400 without modification. See the SCK-915 Developer Guide Section 4 for the full GPIO assignment table and expansion header reference.

SCK-2400-specific addition: the Pico's UART0 (GPIO0/GPIO1), previously wired to the SCK-915 CC1110, connects identically to the SCK-2400 CC1352P's DEBUG_UART (DIO5/DIO16) — same baud rate (115200), same ESP framing, same physical pins on the Pico side.


5.0 C# Ground Station Extension Reference

5.1 Key Methods

Method Description
ActiveHwid Property: current APID from header bar
IncCcsdsSeqCount() Increment and return next CCSDS sequence number
FlushRxQueue() Discard queued received packets before sending
WritePacket(byte[]) Send raw bytes to serial port
WaitForReply(apid, seq, ms) Async: wait for matching CCSDS ACK
CcsdsProtocol.BuildCommand(seq, opcode, args, destApid) Build a CCSDS command packet
CcsdsProtocol.BuildSimpleCommand(seq, opcode, destApid) Build a CCSDS command with no payload
Log(message, color) Append line to main log panel
LogTx(message, hwid) Log transmitted packet in yellow TX format

5.2 Adding a Custom Command (C# Template)

// In SendCustomCommandAsync(), SCK-2400 branch already handles this —
// just add the opcode to CcsdsProtocol.cs and CustomCommand.cs Defaults().

// CcsdsProtocol.cs
public const byte CMD_MY_COMMAND = 0x2A;

// CustomCommand.cs
new CustomCommand {
    Name = "My Command", Opcode = 0x2A, Payload = "",
    Notes = "Description — expects MYRESP:..."
},

For commands requiring custom response handling (e.g. routing to the map or files UI), add a branch in the response-handling section of SendCustomCommandAsync() similar to the existing GPS: prefix check:

if (pkt.PicoPayload.StartsWith("GPS:"))
    HandleGpsPacket(pkt.PicoPayload);

5.3 Opcode Reference

Opcode Name Description
0x01 CMD_GET_TELEM Request telemetry — response via tlm_beacon (APID 0x001)
0x02 CMD_REBOOT Reboot the addressed board
0x03 CMD_GET_CALLSIGN Request callsign string
0x04 CMD_BEACON_CTRL Enable/disable the board's own RF beacon
0x05 CMD_CLEAR_SAFE_MODE Reset NVS reset counter and exit safe mode
0x06 CMD_GET_TIME Request board time
0x10 CMD_OAD_START Begin OAD session
0x11 CMD_OAD_CHUNK Stream one firmware chunk
0x12 CMD_OAD_END Finalize, verify CRC, reboot
0x13 CMD_OAD_ABORT Cancel OAD session
0x14 CMD_OAD_STATUS Query OAD progress, trial state and golden presence
0x15 CMD_OAD_SET_GOLDEN Copy the running, confirmed image to the golden slot (Section 2.4.5)
0x16 CMD_CRYPTO_RESET_REPLAY Clear this board's replay table — local cable only, refused over RF (Section 3.9.3)
0x17 CMD_CRYPTO_STATUS Crypto counters and boot count (Section 3.9.4)
0x20 CMD_PICO_PING Payload bridge — Pico ping
0x21 CMD_PICO_TEMP Payload bridge — temperature
0x22 CMD_PICO_SNAP Payload bridge — camera snapshot
0x23 CMD_PICO_LIST Payload bridge — list SD files
0x27 CMD_GET_GPS GPS+baro fused — response in cmd_ack payload as GPS:lat,lon,alt,sats,fix,hpa,baro_alt,temp_c
0x28 CMD_GET_BARO Barometric only — response as BARO:hpa,baro_alt,temp_c
0x29 CMD_PICO_BEACON Payload beacon on/off
CCSDS_APID_TLM_BEACON (0x001) — Telemetry beacon responses
CCSDS_APID_CMD_ACK (0x003) — All command acknowledgements (including GPS/baro strings)

6.0 Build and Flash Reference

6.1 Building Firmware (CCS Theia)

The Ground Station's Firmware tab drives a headless CCS build:

  1. Set Project Dir to the sck2400_firmware folder
  2. Set Board Role — patches SCK_APID_THIS_BOARD in ccsds.h
  3. Set Hardware — LaunchPad or SCK-2400 V3 (see 6.1.1); selects the CCS configuration, SysConfig file, RF-switch logic, programmer target and BIM
  4. Set RF Power Mode — patches SCK_TXPWR_MODE in radio.h (0 = Bench, 1 = Field)
  5. Click Clean + Build

This runs gmake clean then gmake all, generating SysConfig output, compiling all sources, and linking sck2400_firmware.out / .hex / .map.

Always Clean + Build after modifying ccsds.h, uart.h, or sck2400.syscfg. Incremental builds can link against stale generated headers.

6.1.1 LaunchPad vs SCK-2400 V3 builds — not interchangeable

The same source tree builds for two different boards, and a build for one will not work on the other. The Hardware dropdown must match the board you are flashing.

LaunchPad (LAUNCHXL-CC1352P-2)SCK-2400 V3
ChipCC1352P1F3 (sub-1 GHz + 2.4 GHz)CC2652P1F (2.4 GHz only)
RF switchSkyworks SKY13317-373LF (SP3T)Skyworks SKYA21001 (SPDT)
RF_SWITCH_SKYA21001 (radio.h)01
CCS configuration / SysConfigDebug / sck2400.syscfgV3 / sck2400_v3.syscfg
Programmer target (srfprog)CC1352PCC2652P
BIM hexsck2400_bim\Debug\sck2400_bim\V3\

Why a V3 build fails on a LaunchPad (and the other way round):

  • RF switch. Both boards drive their antenna switch from DIO28/DIO29, but the two switch parts have different truth tables. The SKYA21001 on V3 is strictly complementary (DIO28 high = standard path for RX and bench TX, DIO29 high = 20 dBm PA path; never both). The LaunchPad's SP3T switch decodes the same two lines differently. With the wrong logic the radio is routed to the wrong path or to none, so the link is very weak or silent even though the firmware runs.
  • Different chip. The images are built for different devices (CC2652P vs CC1352P), with different device and CCFG settings. The flash tool is told the target device and won't program the other one, and over OAD the LaunchPad's BIM did not install a V3 image (observed 11/10/2026, Flash Status stayed trial: none).
  • Pins and SysConfig. Each board has its own SysConfig file with its own pin assignments (LEDs, UARTs, SPI). Build only the file that matches the board — see L43.

Testing with a LaunchPad? Pick Hardware = LaunchPad in the Firmware tab and build. That sets RF_SWITCH_SKYA21001 = 0, the Debug configuration and the CC1352P target. A LaunchPad pairs fine with a V3 board over RF: the GS LaunchPad (0x010) and V3 board #1 (0x011) were the test pair for everything in this guide. The radio settings (2440 MHz, 2-GFSK 250 kbps) and the encryption are the same on both boards.

6.2 OAD Image Header Patching

After a successful build, the Ground Station automatically:

  1. Reads oad_entry_vec address from the .map file
  2. Computes imgLen = end - start from the linked sections
  3. Patches .prgEntry and .len in oad_image_header_app.c
  4. Triggers an incremental rebuild to bake the patched values into .out / .hex
  5. Computes the image CRC-32 over bytes [12, len) and writes it into the header at 0x4008 in the hex (PatchSck2400ImageCrc32(), Section 2.4.6). The hex parser fills gaps with 0xFF, so the image matches a J2-flashed one byte for byte
OAD patch: oad_entry_vec at 0x0000D438 (summary table)
OAD patch: computed image len = 0x000096D4 (end=0x0000D6D4)
OAD patch: .prgEntry updated to 0x0000D438
OAD patch: .len updated to 0x000096D4
...
Image CRC32 patched: 0x43256BFB over 0x4E000 bytes

If the patch step reports "already X or pattern not found" for both fields, the existing values already happen to match — this is benign. If only one field reports this, investigate — it usually indicates a stale oad_image_header_app.c from a different build.

6.3 Flashing

The Flash button merges the application hex with BIM (sck2400_merged.hex) and programs the board via srfprog over the XDS110 2-pin cJTAG interface. The merged hex carries the BIM's CCFG, including the ROM bootloader settings. Check it with check_ccfg.py before provisioning (Section 2.4.7):

srfprog -t soc(XDS-<serial>, CC1352P) -e all -p all -v rb -f sck2400_merged.hex

Verify the HEX File path matches your Project Dir. If you change the Project Dir to a non-default location, confirm the HEX File field updates to match — it does not always update automatically (known GS issue, see Section 7).

6.4 Flashing Pico Firmware

mpremote cp main.py :main.py
mpremote cp sdcard.py :sdcard.py

Or hold BOOTSEL on power-up and drag-and-drop to the USB mass storage drive.


7.0 Hard-Won Lessons

These lessons were accumulated during SCK-2400 bringup, building on the SCK-915 lessons (which still apply where the payload board code is shared). Each one cost real debugging time.

# Lesson Impact
L1 OAD_CHUNK_SIZE in firmware must exactly match the Ground Station's chunk size — a mismatch causes every chunk to fail silently with no useful diagnostic. Hit again 11/2026: firmware 128, GS still 240, so all 2496 chunks were NACKed and OAD END reported a CRC failure. Both are now 128 (a 240-byte chunk plus headers and the 21-byte nonce + MAC exceeds the 255 B RF packet) Critical
L2 During OAD, rfTask must sleep only 1ms (not 950ms) to drain the RX queue fast enough for streaming chunks — gated by gOadActive Critical
L3 Closing/reopening ext flash per chunk triggers Deep Power-Down cycling at streaming rates — hold flash open for the whole OAD session High
L4 Each payload command needs its own CCSDS opcode (0x20-0x29) — reusing one opcode with different payload bytes (the SCK-915 PICO_MSG pattern) does not work over CCSDS; the C# SendCustomCommandAsync dispatches on opcode alone Critical
L5 ccsds.h opcode #defines must be identical and present in BOTH the firmware project and the values the C# CcsdsProtocol.cs expects — an undefined opcode compiles silently as an unexpected value, causing dispatch to the wrong handler Critical
L6 uart_task stack must be ≥2048 bytes once payload handlers are added — handle_pico_cmd's static buffers plus the dispatch call chain overflow the original 512-byte stack, causing a silent crash with no error output Critical
L7 Any large (>~100 byte) buffer in uart_task or its call chain must be static, not stack-local — stack overflows in TI-RTOS fail silently Critical
L8 Never call UART2_open() for the payload UART at boot — a floating RX line (Pico not connected) can block indefinitely. Open lazily on first command High
L9 UART2_Mode_NONBLOCKING requires "Enable Nonblocking Mode" checked in SysConfig for that UART instance — otherwise non-blocking reads behave as blocking High
L10 SysConfig UART2 list order determines index number — the first-listed instance is index 0. Reordering instances (even without changing pins) silently swaps which UART your SCK_UART_IDX points to Critical
L11 On this hardware, PAYLOAD_UART (despite its name) is the Ground Station link on DIO12/13 — DEBUG_UART on DIO5/16 is the one available for the Pico bridge. Do not "fix" this naming by changing pins — it breaks the GS link Critical
L12 The Pico's autonomous 10-second beacon races with payload command responses on the bridge UART — send CMD_PICO_BEACON OFF before command sequences Medium
L13 oad_end reboot needs a short delay (200ms) before SysCtrlSystemReset() so the ACK transmits — without it, the GS sees a clean timeout and must rely on beacon resumption to detect success Medium
L14 The Ground Station's HEX File path does not always follow Project Dir changes — verify before flashing to a custom build location Medium
L15 BIM is permanent and never updated by application builds or OAD. A corrupted OAD image is never installed (CRC-16 at OAD END, CRC-32 in the BIM). An installed image that never confirms is replaced by the golden image after 3 boots (Section 2.4) High (safety property)
L16 Always Clean + Build after modifying ccsds.h, uart.h, or .syscfg — incremental builds can silently link stale generated headers High
L17 CC1352P watchdog clock stops when the device enters standby — Power_setConstraint(PowerCC26XX_DISALLOW_STANDBY) is mandatory or the timer never fires on a real hang Critical
L18 CC1352P watchdog does not reset on the first timeout — it fires an NMI first; reset only occurs if the flag is still pending at the second timeout. Total time from hang to reset is ~65s at a 30s period High
L19 Watchdog_open() returns NULL if Watchdog_init() was not called first in mainThread() — same init pattern required as SPI_init() High
L20 With CCS JTAG connected (even background connection without active debug session), Watchdog_DEBUG_STALL_ON pauses the watchdog hardware — the timer never fires. Disconnect JTAG after flash for watchdog testing High
L21 reloadValue passed to the TI Watchdog driver is in milliseconds — the driver calls convertMsToTicks() internally. 30000 = 30 seconds High
L22 TI AESCCM hardware driver produces different keystream than .NET AesCcm for identical inputs — use software AES (RFC 3610 pure C). The hardware driver also causes semaphore poisoning from rfTask context Critical
L23 AES ShiftRows operates on rows of the column-major state: row 3 indices [3,7,11,15] shift left 3 → b[3],b[7],b[11],b[15] = b[15],b[3],b[7],b[11]. Wrong ShiftRows produces incorrect keystream that passes basic tests but mismatches .NET Critical
L24 Moving crypto to uart_task required UART2_Mode_NONBLOCKING, which allocates a ring buffer from the BIOS heap at UART2_open() time, exhausting the heap and causing RF_open() to return NULL (solid LED at boot). Software AES in rfTask eliminates all cross-task crypto issues Critical
L25 SysCtrlSystemReset() (CMD_REBOOT) asserts RSTSRC_PIN_RESET on the LaunchPad XDS110 — not RSTSRC_SYSRESET. The NVS gate must include SCK_RESET_CAUSE_PIN or CMD_REBOOT never increments the reset counter High
L26 usleep() busy-spins on TI-RTOS7 — in watchdogTask, usleep(10000000) completes in microseconds, causing cleanRunAccumMs to hit 300000ms almost instantly and fire nv_storage_on_clean_run() right after nv_storage_on_boot(). Use Task_sleep(10000) Critical
L27 TI NVS_write() returns success and NVS_WRITE_POST_VERIFY passes (reading from write buffer), but data does not survive reset. Use direct FlashSectorErase() + FlashProgram() + FlashCheckFsmForReady() + Power_setConstraint + VIMS cache disable Critical
L28 NVS regionSize must be a multiple of 8192 bytes — any other size causes the linker to place flashBuf0 at 0x0000 (BIM flash) via a synthetic $BOUND$0x0 region. Every write then corrupts BIM Critical
L29 NVS regionBase in SysConfig must match NVS_BASE in the linker command file. The OAD image length filter in the GS app must exclude the NVS section (origin < 0x52000) — otherwise BIM erases NVS on every OAD boot Critical
L30 XDS110 debugger erases NVS flash on every software reset (CMD_REBOOT) on the bench. Test NVS persistence with real power cycles — unplug/replug USB High
L31 The GS board's RF forward is single-slot and holds a 1500 ms reply window after each forward. Streamed OAD chunks were dropped about 99% of the time, and OAD over RF via the GS board had never worked (earlier successes were over direct UART). Forward chunks with expectReply = false and sleep 2 ms in the GS loop Critical
L32 TI's off-chip BIM keeps OAD metadata on external page 0, which is also its factory-image slot. "Revert to factory" re-copied whatever was last sent, so there was no real fallback. The golden image needs its own page, its own marker ("GOLD") and a CRC check before anything is erased Critical
L33 If the BIM project still compiles TI's ccfg_app.c instead of ccfg_sck.c, the build succeeds and ships with the ROM bootloader disabled (BL_CONFIG 0x00FFFFFF). Always run check_ccfg.py on the BIM and merged hex; build_bim_v3.bat uses -Werror=macro-redefined Critical
L34 The OAD header CRC-32 was never computed (left 0xFFFFFFFF, crcStat preset), and TI's CRC32_calc can't read external flash in this BIM. The GS and BIM now compute the same CRC-32/IEEE over [12, len) Critical
L35 When TI's BIM finds nothing valid it parks the chip in low-power mode forever — a permanent brick in orbit. The SCK BIM waits about 10 s and resets, retrying forever Critical
L36 The GS hex parser filled gaps with 0x00. Erased flash is 0xFF, so an OAD image differed from a J2-flashed one and its CRC could never match. Gap fill is 0xFF High
L37 The GS post-OAD reboot poll waited for APID_CMD_ACK, but get_telem answers on APID_TLM_BEACON. Every OAD reported "board did not respond" even when it worked Medium
L38 To test failover, build the update for a different APID and send it to the board's real APID. It never receives a command addressed to it, so it never confirms — a repeatable "can't talk to the ground" image without writing broken code. Use SCK_TRIAL_TIMEOUT_S = 60 for the test and restore 1800 afterwards Medium
L39 Check the destination APID before every command during OAD work. An OAD aimed at the GS board (0x010) over UART erases the GS board's candidate slot, and a get_telem to the wrong APID looks exactly like a dead remote Medium
L40 A nonce built only from the CCSDS sequence number, with one global "last nonce" per board, broke three ways: restarting the GS app (sequence back to 2) locked out a remote that hadn't rebooted, the 14-bit sequence wraps after 16,384 packets (about six OADs), and a command and its reply shared a nonce under the same key. Nonce is now sender + boot count + counter with a per-sender replay table (Section 3.9) Critical
L41 The GS board dropped failed-MAC and replayed packets without counting them, so a crypto rejection looked exactly like a dead radio. It took a second app on the remote's J4 UART, watching its packet counters while the GS board's "packets good" also rose, to see the replies were arriving and being thrown away. CMD_CRYPTO_STATUS (0x17) now shows rejects by reason High
L42 The OAD destination is the APID box, not the Board Role the hex was built for. Two OADs of a remote image went to the GS board in one afternoon. The GS app now checks the build record (Section 8.6) High
L43 The Debug configuration was building both sck2400.syscfg and sck2400_v3.syscfg; the generated files come from whichever runs last. GS LaunchPad builds were right only when the LaunchPad file happened to run second. Exclude the V3 file from Debug (and the LaunchPad file from V3); check the log shows one SysConfig file Medium
L44 Every board on the bench was running the Provision tab's placeholder keys (FF…); the build log warns, but it's easy to miss. Roll and back up real keys before flight or shipping High
L45 CCS builds every .c file in the project folder. A host-side test program dropped in there (its own main(), a 1 MB fake flash) broke the link. Keep test code outside sck2400_firmware Low
L46 "Debug interface is locked" on the first flash of a factory-new CC2652P was a cold solder joint on JTAG_TMSC (chip pin 24), not a locked chip. Reflow pins 24/25 before trying recovery (Section 2.6) High
L47 Two new V3 boards had cold QFN joints (TMSC, then an RF-side pin) despite perfect placement. The footprint's 0.24 × 0.60 mm edge pads were too small for hand-printed paste; enlarged to 0.28 × 0.80 mm (Section 2.6) High
L48 A USB-serial adapter on J4 got no reply because TX and RX were swapped, even after checking twice. Some adapters label pins for what they connect to. If a link that looks correct stays silent, swap TX and RX once first Medium
L49 A V3 board powered from the USB-serial adapter's 3.3 V pin read only 3.1 V and could brown out at +20 dBm TX. Power each V3 board from its own 5 V / 2 A supply Medium
L50 DRC on a copy of the board saved under a different file name runs KiCad's default rules (0.2 mm clearance), not the project's, and reports hundreds of false errors. Run DRC with the board under the project's own file name Low

8.0 Ground Station — SCK-2400 Integration Notes

8.1 Build-Time Patching

Every SCK-2400 build automatically patches four files before compiling:

File What's patched
ccsds.h SCK_APID_THIS_BOARD — board APID
radio.h TX_POWER — bench (0 dBm) or max (+20 dBm)
security.h SCK_AES_KEY_0/1/2 — 3 × 16-byte AES keys from Provision tab
oad_image_header_app.c .prgEntry and .len — OAD image length, capped at origin < 0x52000 to exclude NVS; then the image CRC-32 in the hex header (0x4008)

8.2 Encryption in C

C# sends and receives plaintext CCSDS over USB. All encryption lives in firmware. CcsdsProtocol.cs has no AES dependency. Keys never exist in the C# process — they are patched into security.h at build time only.

8.3 GPS Response Routing

CMD_GET_GPS (0x27) returns its GPS string in a cmd_ack (APID 0x003) payload. The payload begins with the opcode byte (0x27 = ASCII ') followed by GPS:lat,lon,.... Use IndexOf("GPS:") not StartsWith to locate the string. The GPS/Map tab polls automatically every 10 seconds.

8.4 Board-Aware UI

Register board-specific controls in _sck2400OnlyControls or _sck915OnlyControls during Build*() methods. ApplyBoardUi() greys them out and sets tooltips ("SCK-2400 only" / "SCK-915 only"). Called on startup and on board dropdown change.

8.5 RF Crypto Status Indicator

lblRfStatus on the Home tab shows where commands go — the APID box:

Commands → 0x010 (GS board, USB)
Commands → 0x011 (relayed over RF, encrypted)

Updated by UpdateRfStatusLabel() on connect, disconnect, board dropdown change and every edit of the APID box. Before November 2026 it claimed to show the "physical board APID", but that value was only a copy of the APID box at connect time; the app has no way to ask which board is on the USB port.

8.6 OAD Destination Check (build record)

Start OAD sends to the APID box, which is easy to leave on 0x010 (the GS board itself). Since November 2026 every successful SCK-2400 build writes <hex>.sckbuild next to the hex:

{ "Apid": "0x011", "Role": "Remote 1  (APID 0x011)",
  "Hardware": "SCK-2400 V3 (CC2652P, SKYA21001)",
  "Crc32": "0x5B211D8A", "Built": "2026-11-10 14:05:12" }

ConfirmOadDestination() uses it only if its CRC-32 matches the image header of the hex being sent:

  • record ≠ APID box → warning: send to the build's board instead? (Yes switches the APID box too, so Flash Status and Set Golden follow)
  • record = APID box → short confirm with board and CRC
  • no record or stale → warning confirm, default No

SpaceCommsKit SCK-2400 Developer Guide v1.14 For updates and latest version see https://spacecommskit.com/docs