Skip to content

SSC Space Go Ground-to-Ground Interface Control Document

Version: 2.9 Date: June 2026 Based on: OpenAPI Specification ssc-space-go.yaml (Source of Truth)

Document Information

Item Details
Document Title SSC Space Go Ground-to-Ground Interface Control Document
Version 2.9
Status Released
Classification External

Version History

Version Date Changes Author
1.5 Dec 2025 Original DOCX version Tharun Jose
2.0 Jan 2026 Converted to Markdown, aligned with OpenAPI spec Generated from OpenAPI
2.1 Feb 2026 Added CONFIRMED → ONHOLD transition for maintenance; updated booking state descriptions Fredrik Smedberg
2.2 Mar 2026 Added section 8.4 Data Transfer Progress Report; added DataProductsSummary to report structure diagram Fredrik Smedberg
2.3 Mar 2026 Updated and extended data distribution format description with raw format Júlia Tribó Cabré
2.4 Mar 2026 Added the 8.5 section about metrics details Júlia Tribó Cabré
2.5 May 2026 Added the availability check in the general scheduling process Júlia Tribó Cabré
2.6 May 2026 Updated the 4.3 section about scheduling time constraints witht he service tiers Júlia Tribó Cabré
2.7 June 2026 Additional contact states added, see section 4.4 for all the possible states Mathias Nilsson
2.8 June 2026 Updated booking horizons Marcus Näslund
2.9 June 2026 Breaking: replaced GET /post-contact-reports (list) with GET /post-contact-reports/{contact_id} to retrieve a single report by contact ID; updated section 8.1 Oliver Shin

Associated Documents

Document Name Scope Related Sections
SSC Space Go Onboarding Form Customer Configuration Parameters All Contents
SSC Space Go API Reference Detailed API endpoint documentation Scheduling, TLE, Post Contact Reports
Scheduler Sandbox ICD Sandbox testing environment Scheduling API testing

Note: For testing your integration with SSC Space Go scheduling APIs, see the Scheduler Sandbox ICD.

Table of Contents

  1. Introduction and Scope
  2. System Architecture Overview
  3. Authentication and Authorization
  4. SSC Space Go Scheduling
  5. TLE Management
  6. TT&C Gateway
  7. Data Distribution
  8. Post Contact Reporting
  9. Error Handling
  10. Appendix

1. Introduction and Scope

SSC Space Go is a low-cost and autonomous ground station as a service. This Interface Control Document (ICD) defines the customer interfaces to access and benefit from the SSC Space Go service.

1.1 Key System Features

  • Dual-band operation in S and X bands
  • Simultaneous reception (downlink) in both S and X bands with both polarizations
  • Switchable uplink polarization in S band between RHCP and LHCP
  • Autonomous scheduling functionality
  • Real-time Telemetry access and Telecommanding over defined protocols
  • Payload data delivery via S3 protocol to customer endpoints

1.2 API Base URL

/api/v1

Note: All timing references in this document are in UTC according to CCSDS standards.

2. System Architecture Overview

flowchart TB
    subgraph Customer["Customer Systems"]
        MPS["Mission Planning System"]
        MCC["Mission Control Center"]
        DS["Data Storage (S3)"]
    end

    subgraph SSCGo["SSC Space Go Platform"]
        API["API Gateway<br/>/api/v1"]
        SCHED["Scheduler Service"]
        TLE["TLE Manager"]

        subgraph Sites["Ground Station Sites"]
            SEES["SEES (Kiruna)"]
            USAK["USAK (Alaska)"]
            CAIS["CAIS (Inuvik)"]
            CLPA["CLPA (Punta Arenas)"]
            AUWA["AUWA (Western Australia)"]
        end

        subgraph SiteServices["Site Services"]
            TTCGW["TT&C Gateway"]
            DD["Data Distribution"]
        end
    end

    MPS -->|"REST API"| API
    API --> SCHED
    API --> TLE
    MCC -->|"WebSocket"| TTCGW
    DD -->|"S3 Protocol"| DS

    Sites --> SiteServices

2.1 Communication Protocols

Interface Protocol Format
Scheduling API REST/HTTPS JSON
TLE Management REST/HTTPS JSON
TT&C Gateway WebSocket Protobuf
Data Distribution S3 Binary (Data Products)

3. Authentication and Authorization

Access to all SSC Space Go APIs is managed through Microsoft Entra ID (formerly Azure AD). Access control and management will be provisioned as part of the onboarding process, during which the necessary credentials will be created and shared with the customer.

3.1 Authentication Flow

The OAuth 2.0 Client Credentials flow is used for machine-to-machine authentication:

sequenceDiagram
    participant C as Client Application
    participant E as Authorization Server<br/>(Microsoft Entra ID)
    participant A as Resource Server<br/>(SSC Space Go API)

    C->>E: 1. Request Token<br/>(client_id, client_secret, scope)
    E->>E: 2. Validate client credentials
    E->>C: 3. Return token (JWT)
    C->>A: 4. Call API with token
    A->>C: 5. Return data

The response includes how long the token is valid for and lets the customer request a new token whenever the current one expires. The token will be short-lived.

3.2 OAuth 2.0 Configuration

Parameter Description
Token URL https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Scope api://{clientId}/.default
Grant Type client_credentials

3.3 Required Scopes by Endpoint

Scope Endpoints
contacts.view GET /contacts, GET /contacts/{id}, GET /post-contact-reports/{contact_id}, GET /contacts/availability
contacts.create POST /contacts
contacts.cancel DELETE /contacts/{id}
spacecraft.view GET /spacecraft, GET /spacecraft/{id}, GET /spacecraft/{id}/service-types/*/services
sites.view GET /sites, GET /sites/{id}
tle.view GET /spacecraft/{id}/tle
tle.upload POST /spacecraft/{id}/tle

3.4 Using Access Tokens

Once you obtain an access token via the OAuth 2.0 Client Credentials flow (Section 3.1), include it in all API requests using the HTTP Authorization header with the Bearer scheme:

Authorization: Bearer <access_token>

Token Characteristics:

  • Tokens are short-lived (typically 60 minutes)
  • The token response includes an expires_in field indicating validity duration
  • Request a new token before the current one expires
  • The system ensures customers can only access their own spacecraft and services

4. SSC Space Go Scheduling

This section specifies the general framework for interacting with the SSC Space Go Scheduling System. All scheduling functions are available through a RESTful web service API, enabling customers to integrate their mission planning systems directly with SSC Space Go.

For detailed API endpoint documentation, see the SSC Space Go API Reference.

Terminology

Throughout this document, the term "contact" refers to a scheduled communication event between a spacecraft and a ground station. The context determines its specific meaning:

Term Definition
Mission An organizational grouping of one or more spacecraft (e.g., a constellation or program)
Spacecraft A single satellite belonging to a mission, identified by NORAD ID and unique spacecraft_id
Contact Request A customer's request to schedule a contact (API: POST /contacts)
Contact The scheduled communication window with associated resources and state
Contact ID Unique identifier (UUID) assigned to a contact upon creation
Contact Window The time period (start to end) during which the spacecraft is above the horizon mask
Contact Execution The actual satellite pass when TT&C and data services are active

Note: Each spacecraft belongs to exactly one mission. The mission/spacecraft hierarchy supports constellation operations where multiple spacecraft share configuration and billing.

4.1 General Scheduling Process

The customer, through the scheduler, requests a contact for their spacecraft over a specific ground station.

Customer Responsibilities:

  • Authenticate and provide a valid TLE for the contact
  • Calculate the spacecraft visibilities to predict and schedule the necessary start (AOS) time and stop (LOS) time
  • Poll the system to receive confirmation/rejection and check updated status of contacts

The SSC Space Go scheduling system only factors in the availability of resources required to complete the contact service request.

sequenceDiagram
    participant C as Customer
    participant S as SSC Space Go Scheduler

    Note over C: Calculate visibility<br/>using TLE data
    C->>S: Upload TLE
    C->>S: GET /contacts/availability<br/>(Check Availability)
    S->>C: Return availability
    C->>S: POST /contacts<br/>(Request Contact)
    S->>S: Validate Request
    S->>C: 201 Created + contact_id (UUID)

    Note over C: Use contact_id to track progress

    loop Customer Polling
        C->>S: GET /contacts/{contact_id}
        S->>C: Return contact status
    end

    Note over S: Status: NEW → PENDING → CONFIRMED/REJECTED<br/>(confirmed contacts may later move to REVIEW or ONHOLD)

4.2 Contact Request Parameters

A booking request must specify the following parameters:

Parameter Description
site Specific ground station site from the SSC Space Go network
spacecraft Specific spacecraft name/acronym (crucial for constellation management)
start Contact start time, rounded down to the closest minute
end Contact end time, rounded up to the closest minute
service Contact configuration made available from customer onboarding

Upon reception of a valid contact request, the customer receives a response with a contact_id (UUID) that enables:

  • Tracking the progress of the contact request
  • Polling the system to receive confirmation/rejection
  • Continuously checking the updated status of the contact

4.3 Scheduling Time Constraints

Constraint Value
Minimum Schedule Request Time 1 hour before contact
Minimum Contact Duration 1 minute
Maximum Contact Duration 12 minutes

The maximum schedule request horizon is determined by the service tier assigned to each spacecraft during onboarding. Three tiers are available — BASIC, ADVANCED, and PREMIUM — each offering a different scheduling horizon as shown below.

Service Tier Maximum Schedule Request Horizon
BASIC 2 days in advance
ADVANCED 4 days in advance
PREMIUM 10 days in advance

4.4 Booking States

Since a contact request is for an anticipated event, there are different schedule states. A confirmed contact could also update/change state depending on unforeseen resource constraints. It is the customer's responsibility to poll and check for the latest state.

stateDiagram-v2
    [*] --> NEW: Contact Request
    NEW --> PENDING: Resources Available
    NEW --> REJECTED: No Resources
    PENDING --> CONFIRMED: Site Confirmed
    CONFIRMED --> REVIEW: Issue Detected
    CONFIRMED --> ONHOLD: Service Unavailable
    REVIEW --> CONFIRMED: Issue Resolved
    ONHOLD --> CONFIRMED: Issue Resolved
    ONHOLD --> CANCELLED: Customer Cancel
    CONFIRMED --> ONGOING: Contact in progress
    ONGOING --> POST_CONTACT: Contact is over
    CANCELLED --> [*]
    REJECTED --> [*]
    POST_CONTACT --> SUCCESS
    POST_CONTACT --> PARTIAL_SUCCESS
    POST_CONTACT --> FAIL
    POST_CONTACT --> UNKNOWN: All internal data is not avail
    UNKNOWN --> UNKNOWN
    UNKNOWN --> SUCCESS
    UNKNOWN --> PARTIAL_SUCCESS
    UNKNOWN --> FAIL
State Description
NEW Contact request received and being processed
PENDING Resources identified, awaiting site confirmation.
CONFIRMED Contact confirmed, resources locked
REJECTED Insufficient resources for requested period
REVIEW Issues identified that may impact service quality (e.g., old TLE). Service will still be provided but might be degraded
ONHOLD Service is unavailable due to internal service issues; customer may cancel or wait for resolution
CANCELLED Contact has been cancelled by the customer
ONGOING Contact is currently running
POST_CONTACT The contact has ended; outcome validation is in progress
SUCCESS All services for the contact started successfully
PARTIAL_SUCCESS Some, but not all, services for the contact started successfully
FAIL No services for the contact started successfully
UNKNOWN Assessment data is not yet fully available

Important: Contact cancellation requests can only be made when the contact is in an ONHOLD state. No other contact state shall allow the customer to request a contact cancellation.

Note: If SSC Space Go resolves the issue before the contact starts, the contact will automatically transition back to CONFIRMED without any action required from the customer. If you choose to keep the contact, continue polling via GET /contacts/{id} to monitor the state.

Cancellation Policy:

  • Customers cannot directly cancel contacts in CONFIRMED, PENDING, or REVIEW states
  • The ONHOLD state is set by SSC Space Go when when there are internal service issues that will prevent service delivery
  • Once a contact transitions to ONHOLD, the customer can decide to cancel via DELETE /contacts/{id}

5. TLE Management

Customers must provide valid Two-Line Element (TLE) data for their spacecraft to enable accurate tracking during contacts.

For detailed API endpoint documentation, see the SSC Space Go API Reference.

5.1 TLE Requirements

  • Customers are responsible for uploading and maintaining current TLE data
  • TLE data is used by the ground station for antenna pointing during contacts
  • The system validates TLE epoch freshness against scheduled contact times

TLE Freshness Guidelines:

Condition System Behavior
TLE epoch within 48 hours of contact Normal processing
TLE epoch older than 48 hours Contact may be placed in REVIEW state
TLE epoch significantly outdated Contact may be rejected

Recommendation: Upload fresh TLE data at least every 48 hours for LEO satellites to ensure optimal antenna tracking accuracy.

5.2 TLE Data Format

TLE data follows the standard two-line format:

{
  "line1": "1 25544U 98067A   08264.51782528 -.00002182  00000-0 -11606-4 0  2927",
  "line2": "2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537"
}

6. TT&C Gateway

The TT&C Gateway provides real-time access to Telemetry (TM) and Telecommand (TC) services during contacts via WebSocket connections. Each site has its own TT&C Gateway; the customer needs to know the specific contact site to connect to.

6.1 TT&C Gateway Overview

flowchart LR
    subgraph Customer["Customer MCC"]
        TMC["TM Client"]
        TCC["TC Client"]
    end

    subgraph Site["Ground Station Site"]
        TTCGW["TT&C Gateway"]
        ANT["Antenna System"]
    end

    subgraph Space["Space Segment"]
        SC["Spacecraft"]
    end

    TMC <-->|"WebSocket/Protobuf<br/>TM Service (v2)"| TTCGW
    TCC <-->|"WebSocket/Protobuf<br/>TC Service (v2)"| TTCGW
    TTCGW <-->|"Baseband<br/>Interface"| ANT
    ANT <-->|"S-Band<br/>RF Link"| SC

6.2 Service Specifications

The TT&C Gateway operates in S-band and X-band for real-time telemetry and telecommand services:

Service Band Frequency Polarization
Telecommand (uplink) S-band 2025 MHz - 2120 MHz RHCP or LHCP (selectable)
Telemetry (downlink) S-band 2200 MHz - 2300 MHz Single or simultaneous RHCP/LHCP
Telemetry (downlink) X-band 7900 MHz - 8400 MHz Single or simultaneous RHCP/LHCP

Note: Payload data downlink is delivered via S3 through the Data Distribution service (see Section 7).

Access to the TT&C Gateway is managed through Microsoft Entra ID (same as Scheduling API).

6.2.1 Site Gateway URLs

Site-specific gateway URLs (the <station_base_url> in WebSocket URLs) are provided during customer onboarding. Contact your SSC Space Go representative for access credentials and endpoint URLs for each site.

6.3 Connection Lifecycle

sequenceDiagram
    participant C as Customer
    participant GW as TT&C Gateway
    participant SC as Spacecraft

    Note over GW: Service instantiated<br/>~minutes before contact
    C->>GW: WebSocket Connect + Auth Token
    GW->>GW: Validate Token
    GW->>C: Connection Established

    Note over GW,SC: Contact Period
    SC->>GW: Downlink TM
    GW->>C: Stream TM Data
    C->>GW: TC Request
    GW->>SC: Uplink TC
    GW->>C: TC Acknowledgment

    Note over GW: Contact End
    GW->>C: EndOfContact Event
    GW->>C: Connection Closed

6.3.1 WebSocket Close Codes

The TT&C Gateway uses standard WebSocket close codes:

Code Name Description
1000 Normal Closure Graceful shutdown after EndOfContact or client-initiated close
1011 Internal Server Error Server-side error during message processing

Connection Behavior:

  • After sending EndOfContact, the gateway waits briefly (500ms) before closing the connection
  • Write timeout is 2 seconds - slow clients may be disconnected
  • If the client does not close the connection after EndOfContact, the gateway will close it

6.4 Telemetry (TM) Service

The TM service streams downlink telemetry data to the customer during contacts.

URL Schema: 

wss://<station_base_url>/<version>/<spacecraft_id>/<site_id>/<service_id>?format=<format>

Parameters:

Parameter Description
station_base_url Site-specific gateway URL (provided separately)
version API version (v2)
spacecraft_id Unique spacecraft identifier
site_id Unique site identifier
service_id TM
format Message format (protobuf)

Service Characteristics:

  • Service instantiated minutes before scheduled contact start
  • Maximum 2 concurrent connections per TM service
  • TM streamed in real-time (no buffering - network issues may cause TM loss)
  • TM is also recorded and delivered via Data Distribution for offline recovery
  • EndOfContact event sent at contact completion
  • LossFrameSync notifications sent when frame sync is lost

TM Protobuf Message Definition:

syntax = "proto3";
import "google/protobuf/timestamp.proto";
package ssc.connect.proto.ttc_gateway.v1;

message TmServiceMsg {
  oneof msg {
    TmDataMsg tm_data = 1;
    EndOfContact end_of_data = 2;
    // Field 3 reserved
    LossFrameSyncNotif loss_frame_sync = 4;
  }
}

enum TmFrameQuality {
  TM_FRAME_QUALITY_UNSPECIFIED = 0;  // Quality unknown
  TM_FRAME_QUALITY_GOOD = 1;          // No errors or errors corrected
  TM_FRAME_QUALITY_BAD = 2;           // Contains unrecoverable errors
}

enum TmType {
  TM_TYPE_UNSPECIFIED = 0;
  TM_TYPE_CADU = 1;   // ASM + TM Frame + ReedSolomon
  TM_TYPE_CCSDS = 2;  // CCSDS TM Frame (AOS or Transfer frame)
  TM_TYPE_OTHER = 3;  // Unspecified TM data
}

message TmDataMsg {
  google.protobuf.Timestamp ert = 1;  // Earth Received Time (UTC)
  string site_id = 2;
  TmFrameQuality frame_quality = 3;
  TmType tm_type = 4;
  bytes tm_data = 5;
  int32 bits_corrected = 6;
}

message LossFrameSyncNotif {
  google.protobuf.Timestamp notif_time = 1;
}

message EndOfContact {
  google.protobuf.Timestamp notif_time = 1;
}

The TmType of the TmDataMsg delivered via TmServiceMsg is configured per spacecraft during onboarding. This determines the format of the tm_data bytes field. Customers should confirm the expected TmType for their spacecraft with their SSC Space Go representative during onboarding.

6.5 Telecommand (TC) Service

The TC service enables uplink commanding to the spacecraft.

URL Schema: 

wss://<station_base_url>/<version>/<spacecraft_id>/<site_id>/<service_id>?format=<format>

Service Characteristics:

  • Service instantiated minutes before scheduled contact start
  • Maximum 1 connection per TC service
  • Maximum command size: 65,535 bytes

Command Queue Behavior:

Property Value
Queue Size 100 commands maximum
Queue Type Per-connection FIFO (First-In, First-Out)
Overflow Behavior New commands rejected with TC_RECEPTION_ERROR_TC_BUFFER_FULL
Queue Clearing All buffered TCs cleared on MODEM connection loss or radiation error

Commanding Status States:

State Definition Status Reasons
UNSPECIFIED System not ready to transmit TC Contact not officially started, OR antenna pointing below horizon mask
READY Antenna ready to transmit TCs Contact started and antenna above horizon mask

Note: If a command is sent when status is UNSPECIFIED, the command will be rejected with TC_RECEPTION_ERROR_COMMAND_STATUS_NOT_READY.

TC Request Handling:

  • Each TC request must contain a tcId (monotonically increasing sequence number)
  • If tcId does not match expected value, the request is rejected
  • On loss of SSC Space connectivity to MODEM or radiation error: uplink state transitions to UNSPECIFIED, all buffered TCs are cleared with Unknown status
  • On customer-gateway connection loss: all received TCs will be radiated

TC Protobuf Message Definition:

syntax = "proto3";
import "google/protobuf/timestamp.proto";
package ssc.connect.proto.ttc_gateway.v1;

message TcServiceRequest {
  oneof msg {
    SendTcRequest send_tc = 1;
  }
}

message TcServiceResponse {
  oneof msg {
    TcReceivedAck send_tc_ack = 1;
    TcRadiationAck tc_rad_ack = 2;
    CommandingStatusUpdate cmd_status_update = 3;
  }
}

message SendTcRequest {
  uint32 tc_id = 1;
  bytes encoded_tc = 2;
}

enum CommandingStatus {
  COMMANDING_STATUS_UNSPECIFIED = 0;
  COMMANDING_STATUS_READY = 1;
}

message CommandingStatusUpdate {
  google.protobuf.Timestamp update_time = 1;
  CommandingStatus commanding_status = 2;
}

enum TcReceptionError {
  TC_RECEPTION_ERROR_UNSPECIFIED = 0;
  TC_RECEPTION_ERROR_INVALID_TC_ID = 1;        // TC ID does not match expected
  TC_RECEPTION_ERROR_TC_BUFFER_FULL = 2;       // TC buffer is full
  TC_RECEPTION_ERROR_TC_TOO_BIG = 3;           // TC size exceeds maximum
  TC_RECEPTION_ERROR_OUT_OF_PROVISION_TIME = 4; // TC rejected: outside contact time
  TC_RECEPTION_ERROR_COMMAND_STATUS_NOT_READY = 5; // TC rejected: commanding not ready
}

message TcReceivedAck {
  uint32 tc_id = 1;
  bool success = 2;
  optional TcReceptionError err_code = 3;
}

enum TcRadiationError {
  TC_RADIATION_ERROR_UNSPECIFIED = 0;
  TC_RADIATION_ERROR_PRODUCTION_ERROR = 1;
}

message TcRadiationAck {
  uint32 tc_id = 1;
  google.protobuf.Timestamp rad_stop_time = 2;
  optional TcRadiationError err_code = 3;
}

6.6 URL Error Codes

Error Code Description
HTTP 404 Invalid URL path parameter or service not active
INVALID_SPACECRAFT Spacecraft ID not found
INVALID_SITE Site ID not found
INVALID_SERVICE Service configuration not found
UNAUTHORIZED Authentication failed
SERVICE_UNAVAILABLE Service not available for contact

7. Data Distribution

SSC Space Go delivers recorded payload data and telemetry to customer-specified S3-compatible storage endpoints.

7.1 Data Distribution Overview

flowchart LR
    subgraph Space["Space Segment"]
        SAT["Spacecraft"]
    end

    subgraph Site["Ground Station"]
        ANT["Antenna"]
        SDR["SDR Modems"]
        DPG["Data Product<br/>Generator"]
    end

    subgraph Network["WAN"]
        DD["Data Distribution<br/>Service"]
    end

    subgraph Customer["Customer"]
        S3["S3 Storage<br/>Endpoint"]
    end

    SAT -->|"RF"| ANT
    ANT --> SDR
    SDR -->|"TM Recording"| DPG
    DPG -->|"Data Product"| DD
    DD -->|"S3 REST API<br/>(Multipart Upload)"| S3

This ICD defines the interface for Data Product delivery over S3.

Applicable for:

  • Payload data downlinked in X-band (7900 MHz - 8400 MHz)
  • Telemetry recording in S-band (2200 MHz - 2300 MHz)

7.2 Delivery Endpoint Configuration

The Data Product will be pushed to an S3-compatible endpoint specified by the customer. The necessary information pertaining to the customer endpoint and configuration shall be shared with SSC Space during the onboarding phase.

During onboarding, the customer must specify if the defined endpoint is valid for all supported missions, or if each mission has its own appropriate endpoint.

Note: It is the customer's responsibility to notify SSC Space of any updates to endpoint configuration.

7.3 Authorization Methods

SSC Space relies on AWS S3 REST API for data delivery. Two authorization methods are supported:

7.3.1 Dedicated IAM User

The customer provisions a service principal with correct permissions for SSC Space to use.

Configuration Description
URL S3 Bucket endpoint where Data Products will be delivered
Access Key Access key to access the storage bucket
Secret Key Associated secret key to access the storage bucket

7.3.2 S3 Access Grants

The customer creates a unique account ID granting access to the storage bucket for SSC Space to request temporary credentials.

Example Response: 

{
  "Credentials": {
    "AccessKeyId": "Example-key-id",
    "SecretAccessKey": "Example-access-key",
    "SessionToken": "Example-session-token",
    "Expiration": "2023-06-14T18:56:45+00:00"
  },
  "MatchedGrantTarget": "s3://amzn-s3-demo-bucket/prefixA**"
}

7.4 S3 Compatibility

SSC Space Go Data Distribution is compatible with any S3-compatible Object Storage Endpoint.

  • Supports multipart uploads for endpoint compatibility
  • Maximum object size: 5 TB
  • Part size: 5 MB - 5 GB

If there are other specific size restrictions depending on the S3 endpoint, this must be communicated during the onboarding process.

7.5 Data Product File Format

The Data Product file format is agreed with the customer during the onboarding phase. SSC Space Go supports two output formats:

Format Description
Raw Raw recorded payload data, delivered without additional framing. Default format.
SSC TLM v0 Providing structured access to individual TM Data Units with timing and quality metadata.

The selected format applies to all Data Products delivered to the customer's endpoint. If a change of format is required after onboarding, this must be communicated to SSC Space.

7.5.1 File Naming Convention

{spacecraft}_{site}_{rfBand}_{polarization}_{channelId}_{startTime}_{endTime}_{contactId}.tlm
Field Description Example
spacecraft Spacecraft acronym (agreed with customer) EXSAT
site Ground station acronym SEES
rfBand RF band (S/X/Ka) S
polarization Signal polarization (LH/RH) RHCP
channelId Channel identifier (default "0" = no redundant recording) 0
startTime Recording start (UTC) 2025-01-15T100000.000
endTime Recording end (UTC) 2025-01-15T101500.000
contactId Contact UUID (version 4) 550e8400...

Note: Data received in both polarizations are delivered as separate data products.

7.5.2 Bit and Byte Ordering Convention

Bit Ordering: The first bit in the field to be transmitted or read (the leftmost significant bit) is defined as BIT 0. Following bits are named BIT 1 through BIT N-1. BIT 0 is the most significant bit and the first transmitted bit when expressing a binary value.

Byte Ordering: All multi-byte integer fields in the Data Product header use big-endian (network byte order) encoding. The most significant byte is stored first.

7.5.3 SSC TLM v0 File Structure

This section applies only to customers using the SSC TLM v0 format.

Show details The Data Product File contains several blocks, each containing a Header and a TM Data Unit: 
flowchart TB
    subgraph DataProduct["Data Product File (.tlm)"]
        direction TB
        B1["Block 1"]
        B2["Block 2"]
        dots["..."]
        BN["Block N"]
    end

    subgraph BlockStructure["Each Block Contains:"]
        direction TB
        H["Header<br/>(15 bytes, Version 0)"]
        TDU["TM Data Unit<br/>(variable length)"]
        H --> TDU
    end

    B1 -.- BlockStructure
    B2 -.- BlockStructure
    BN -.- BlockStructure

7.5.4 Header Format (Version 0)

This section applies only to customers using the SSC TLM v0 format.

Show details

The header is 15 bytes total and contains information about the following TM Data Unit:

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              Header Version 0 (15 bytes)                            │
├──────────┬─────────┬───────┬──────────────────┬───────────────────┬─────────────────┤
│ Version  │ Quality │ Spare │ TM Data Unit     │ Earth Received    │ Number of       │
│ (4 bits) │ (2 bits)│(2 bit)│ Size (3 octets)  │ Time (9 octets)   │ Corrected bits  │
│          │         │       │                  │                   │ (2 octets)      │
├──────────┴─────────┴───────┼──────────────────┼───────────────────┼─────────────────┤
│         1 octet            │     3 octets     │     9 octets      │    2 octets     │
└────────────────────────────┴──────────────────┴───────────────────┴─────────────────┘
Field Size Format Description
Version 4 bits Unsigned int Fixed to 0 for current version
Quality 2 bits Enum TM Data Quality: 00=Good, 01=Bad, 11=Unknown, 10=Unused
Spare 2 bits - Reserved for future use (set to 0)
TM Data Unit Size 3 octets Unsigned int Size of TM Data Unit (0-16,777,215 bytes)
Earth Received Time 9 octets See below Timestamp when data was received
Corrected bits 2 octets Unsigned int Number of bits corrected (GOOD quality only). FFFF=corrections made but count unknown

Earth Received Time Format:

┌─────────────────────────────────────────────────────────────────┐
│                  Earth Received Time (9 octets)                 │
├───────────────────────────────────┬─────────────────────────────┤
│    Seconds from Posix Epoch       │ Nanoseconds within second   │
│           (5 octets)              │         (4 octets)          │
└───────────────────────────────────┴─────────────────────────────┘
  • Seconds from Posix Epoch: 5-byte big-endian signed integer, seconds since January 1, 1970 (midnight UTC/GMT). Valid range: approximately years 1653 to 2286.
  • Nanoseconds: 4-byte big-endian unsigned integer. Value must be between 0 and 999,999,999. Any other value is considered incorrect.

7.5.5 Supported TM Protocols

  • CCSDS TM Transfer Frame
  • CCSDS AOS Frame
  • CCSDS USLP Transfer Frame
  • CCSDS CADU
  • CSP (Cubesat Space Protocol)

7.6 Error Handling

Transient Errors (automatic retry):

  • Temporary network outages
  • Service unavailability

Permanent Errors (customer notification required):

  • Customer S3 endpoint unavailable (status code 5xx)
  • Credentials not valid
  • Server certificate expired
  • Customer storage out of disk space

Data products are retained for 72 hours (3 days) for redelivery after a delivery failure. After this retention period, undelivered data products are permanently deleted. When a delivery error occurs (e.g., S3 endpoint unavailable, invalid credentials), it is the customer's responsibility to correct the issue and notify SSC Space promptly so that redelivery can be attempted within the retention window.

8. Post Contact Reporting

Post Contact Reports provide an overview of completed contacts, including whether the contact was aborted, individual reports for each signal channel with payload, telemetry, or telecommand statistics, and data transfer progress reporting for data products.

For detailed API endpoint documentation, see the SSC Space Go API Reference.

8.1 Report Availability

  • Reports are generated automatically after contact completion
  • Retrieve a report with GET /post-contact-reports/{contact_id}, which returns the complete report (including metrics) for a single contact
  • If a contact was aborted, aborted: true is set and no signal channel data is included

8.2 Report Structure

classDiagram
    class PostContactReport {
        +string contact_id
        +string mission_id
        +string mission_name
        +string spacecraft_id
        +string spacecraft_name
        +string site_id
        +string site_name
        +string contact_service_config_id
        +string contact_service_config_name
        +string contact_service_config_description
        +datetime start
        +datetime end
        +boolean aborted
        +SignalChannelReport[] channels
        +Metric[] antenna_metrics
        +DataProductsSummary data_products_summary
    }

    class SignalChannelReport {
        +integer channel_number
        +string description
        +string rf_band
        +string polarization
        +boolean unrecoverable_error
        +TCStatistics tc_statistics
        +SignalChannelMetrics metrics
    }

    class TCStatistics {
        +integer tc_received
        +integer tc_rejected
        +integer tc_processed
        +integer tc_radiated
    }

    class DataProductsSummary {
        +integer data_products_created_count
        +integer data_products_delivered_count
        +DataProductStatus[] data_products
    }

    class DataProductStatus {
        +string id
        +string name
        +string status
        +boolean transfer_successful
        +datetime last_transfer_attempt_at
    }

    class SignalChannelMetrics {
      <<oneOf>>
    }

    SignalChannelMetrics <|-- Dvbs2PayloadMetrics
    SignalChannelMetrics <|-- PayloadMetrics
    SignalChannelMetrics <|-- TelemetryMetrics

    class Dvbs2PayloadMetrics {
      +Metric[] dvbs2_payload_metrics
    }

    class PayloadMetrics {
      +Metric[] payload_metrics
    }

    class TelemetryMetrics{
      +Metric[] telemetry_metrics
    }

    class Metric {
        +string name
        +string unit
        +MetricValue[] values
    }

    class MetricValue {
        +datetime time
        +integer|float|string value
    }

    PostContactReport --> SignalChannelReport
    PostContactReport --> DataProductsSummary
    PostContactReport --> Metric
    SignalChannelReport --> TCStatistics
    SignalChannelReport --> SignalChannelMetrics
    DataProductsSummary --> DataProductStatus
    Metric --> MetricValue
    Dvbs2PayloadMetrics --> Metric
    PayloadMetrics --> Metric
    TelemetryMetrics --> Metric

8.3 Unrecoverable Error

The unrecoverable_error field in SignalChannelReport is set to true if a signal channel's software defined radio does not start before the contact begins, resulting in an unrecoverable state for that channel.

8.4 TC Statistics Details

TC statistics are included in every signal channel report. For contacts without uplink traffic, all TC statistics values are zero.

Telecommand Statistics:

  • tc_received - Commands received from customer
  • tc_rejected - Commands that failed to be processed
  • tc_processed - Commands successfully processed
  • tc_radiated - Commands successfully transmitted to spacecraft

Possible reasons for a TC failing to be processed include:

  • The TC is sent outside the contact time
  • The TC ID does not match the expected value
  • The buffer is full
  • The TC size exceeds the allowed limit
  • The commanding status is not ready

8.5 Metrics Details

Each contact report contains two types of metrics:

  • Antenna metrics: Reported at the top level of the PostContactReport. These are always present for every contact.
  • Receiver-specific metrics: Each signal channel has metrics depending on the type of receiver used. The receiver types are: DVB-S2 receiver, Wideband receiver, and Telemetry receiver.

Metrics are delivered for each second of a contact. Below are the expected metrics for each type:

Antenna Metrics

Name Unit
elevation_commanded degrees
elevation_actual degrees
azimuth_commanded degrees
azimuth_actual degrees

DVB-S2 Metrics

Name Unit
eb_n0 dB
es_n0 dB
carrier_frequency_offset MHz
pl_frame_sync_lock NA
detected_modcod NA
symbol_rate ksym/s
carrier_lock NA
symbol_lock NA
pl_frame_sync_lock_frames NA
pl_frame_sync_lock_losses NA
dummy_frames NA
bch_correctable NA
bch_uncorrectable_delta NA

Payload Metrics

Name Unit
carrier_lock NA
eb_n0 dB
es_n0 dB
symbol_lock NA
carrier_frequency_offset MHz

Telemetry Metrics

Name Unit
eb_n0 dB
carrier_lock_state NA
symbol_lock_state NA
carrier_frequency_offset MHz

8.6 Data Transfer Progress Report

The data_products_summary field provides visibility into data product creation and delivery status for a contact. Customers can poll the Post Contact Report to track data transfer progress as it evolves after contact completion. This field is optional and may be absent for contacts that were aborted or where no data products were created.

Summary Fields:

  • data_products_created_count - Total number of data products created for the contact
  • data_products_delivered_count - Number of data products successfully delivered

Data Product Status Fields:

Each entry in the data_products array contains:

  • id - Unique data product (artifact) identifier
  • name - Data product name or location
  • status - Aggregated processing record status, one of:
  • PROCESSING_RECORD_STATUS_UNSPECIFIED - Status not yet determined
  • PROCESSING_RECORD_STATUS_PENDING - Queued or currently being processed
  • PROCESSING_RECORD_STATUS_SUCCESS - Processing completed successfully
  • PROCESSING_RECORD_STATUS_FAILED - Processing failed
  • transfer_successful - Whether the data transfer completed successfully
  • last_transfer_attempt_at - Timestamp of the most recent transfer attempt

9. Error Handling

9.1 HTTP Status Codes

Code Description
200 Success
201 Created
204 No Content (successful deletion)
400 Bad Request - Invalid input
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource does not exist
500 Internal Server Error

9.2 Problem Response Format

Error responses use application/problem+json format:

{
  "title": "Invalid Request",
  "detail": "The spacecraft_id 'invalid-id' does not exist",
  "trace_id": "abc123-def456-ghi789"
}
Field Type Description
title string Short problem summary
detail string Detailed description
trace_id string Unique request trace ID

9.3 Common Issues and Solutions

Issue Possible Cause Solution
Contact stuck in PENDING Site confirmation delayed Poll periodically; contact SSC Space support if persists > 24 hours
Contact moved to REVIEW TLE data outdated (> 48 hours old) Upload fresh TLE data for the spacecraft
WebSocket connection refused Service not yet instantiated Wait until closer to contact start time; verify contact is CONFIRMED
Authentication fails (401) Token expired or invalid Request new token via OAuth 2.0 flow
S3 delivery failing Endpoint unavailable or credentials invalid Verify S3 endpoint accessibility and credential validity
TC commands rejected Commanding status is UNSPECIFIED Wait for antenna to reach READY state (above horizon mask)
TM frames dropped Network latency or slow client Ensure client can process frames within 2-second write timeout

Tip: Always include the trace_id from error responses when contacting SSC Space support for faster issue resolution.

10. Appendix

10.1 Acronyms

Acronym Definition
AOS Acquisition of Signal
API Application Programming Interface
CADU Channel Access Data Unit
CCSDS Consultative Committee for Space Data Systems
CSP Cubesat Space Protocol
IAM Identity and Access Management
ICD Interface Control Document
JWT JSON Web Token
LHCP Left Hand Circular Polarization
LOS Loss of Signal
MCC Mission Control Center
NORAD North American Aerospace Defense Command
RHCP Right Hand Circular Polarization
SDR Software Defined Radio
TC Telecommand
TLE Two-Line Element
TM Telemetry
TT&C Telemetry, Tracking & Command
USLP Unified Space Link Protocol
UTC Coordinated Universal Time
UUID Universally Unique Identifier
WAN Wide Area Network

10.2 Frequency Band Definitions

SSC Space Go supports the following frequency bands:

Band Direction Frequency Range Service Polarization
S-band Uplink (TC) 2025 - 2120 MHz Telecommand RHCP or LHCP (selectable)
S-band Downlink (TM) 2200 - 2300 MHz Telemetry, Payload Data RHCP, LHCP, or both
X-band Downlink only 7900 - 8400 MHz Telemetry, Payload Data RHCP, LHCP, or both

Note: X-band is receive-only (no uplink capability). Payload data is delivered via S3 through the Data Distribution service.

10.3 API Quick Reference

For complete API endpoint documentation including request/response schemas, see the SSC Space Go API Reference.

Method Endpoint Description
GET /contacts List contacts
POST /contacts Create contact
GET /contacts/{id} Get contact
DELETE /contacts/{id} Cancel contact (ONHOLD only)
GET /contacts/availability Get availability
GET /post-contact-reports/{contact_id} Get report for a contact
GET /spacecraft List spacecraft
GET /spacecraft/{id} Get spacecraft
GET /spacecraft/{id}/tle Get TLE
POST /spacecraft/{id}/tle Upload TLE
GET /spacecraft/{id}/service-types/{type}/services List services
GET /sites List sites
GET /sites/{id} Get site