openapi: 3.0.3
info:
  title: Trimble Mobile Manager API
  description: >-
    The Trimble Mobile Manager (TMM) API provides developer interfaces for
    integrating high-accuracy GNSS positioning from connected Trimble receivers
    into custom mobile applications. Offers a local REST API for system
    information and WebSocket stream initiation, plus real-time GNSS position
    delivery via WebSocket. Supports Trimble Catalyst DA2, R580, R780, R12i,
    R980, and SP100 receivers. Runs locally on Android or iOS devices where
    Trimble Mobile Manager is installed.
  version: 1.0.0
  contact:
    url: https://developer.trimble.com/docs/mobile-manager/
servers:
  - url: http://localhost:{apiPort}
    description: Local Trimble Mobile Manager API server (running on device)
    variables:
      apiPort:
        default: '8080'
        description: API port returned by tmmInfo endpoint
security:
  - basicAuth: []
paths:

  /api/v1/tmmInfo:
    get:
      operationId: getTmmInfo
      summary: Get TMM System Information
      description: >-
        Retrieve system information about the connected Trimble Mobile Manager
        instance, including the API port, WebSocket ports, connected receiver
        details, and version information.
      tags:
        - System
      responses:
        '200':
          description: TMM system information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmmInfo'
        '401':
          description: Unauthorized - invalid access code

  /api/v1/positionStream:
    get:
      operationId: startPositionStream
      summary: Start Position Stream
      description: >-
        Initiates position streaming from the connected GNSS receiver. Returns
        the WebSocket port number for connecting to the position stream.
        After calling this endpoint, open a WebSocket connection to
        ws://localhost:{port} to receive real-time GNSS position data.
      tags:
        - Positioning
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [locationV1, locationV2]
            default: locationV2
          description: >-
            Position data format version. locationV2 includes extended fields
            for IMU orientation, TIP positions, and reference frame data.
      responses:
        '200':
          description: WebSocket port for position stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionStreamResponse'
        '401':
          description: Unauthorized

  /api/v1/receiver/info:
    get:
      operationId: getReceiverInfo
      summary: Get Receiver Information
      description: >-
        Returns information about the currently connected GNSS receiver including
        model, serial number, firmware version, and connection status.
      tags:
        - Receiver
      responses:
        '200':
          description: Receiver information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiverInfo'
        '401':
          description: Unauthorized

  /api/v1/receiver/status:
    get:
      operationId: getReceiverStatus
      summary: Get Receiver Status
      description: Returns current status of the connected GNSS receiver.
      tags:
        - Receiver
      responses:
        '200':
          description: Receiver status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiverStatus'

  /api/v1/corrections/status:
    get:
      operationId: getCorrectionsStatus
      summary: Get Corrections Status
      description: >-
        Returns the current status of GNSS correction services being applied
        to the receiver (e.g., RTX, RTK, SBAS).
      tags:
        - Corrections
      responses:
        '200':
          description: Corrections status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrectionsStatus'

  /api/v1/corrections/configure:
    post:
      operationId: configureCorrections
      summary: Configure Corrections
      description: >-
        Configure the GNSS correction source for the connected receiver.
        Supports CenterPoint RTX, SBAS, and custom NTRIP mountpoints.
      tags:
        - Corrections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorrectionsConfig'
      responses:
        '200':
          description: Corrections configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorrectionsStatus'
        '400':
          description: Invalid configuration

  /api/v1/catalyst/licenses:
    get:
      operationId: getCatalystLicenses
      summary: Get Catalyst Licenses
      description: Returns available Trimble Catalyst licenses for the connected DA2 receiver.
      tags:
        - Catalyst
      responses:
        '200':
          description: Available Catalyst licenses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CatalystLicense'

  /api/v1/catalyst/licenses/activate:
    post:
      operationId: activateCatalystLicense
      summary: Activate Catalyst License
      description: >-
        Activate a Trimble Catalyst On Demand license to enable precision
        corrections for the DA2 receiver.
      tags:
        - Catalyst
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [licenseId]
              properties:
                licenseId:
                  type: string
                  description: Catalyst license identifier
      responses:
        '200':
          description: License activated

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Access code generated using SHA256 hash of (applicationId + currentUTCTime),
        Base64 encoded. Valid for 1 second only. Must be regenerated per request.

  schemas:
    TmmInfo:
      type: object
      description: Trimble Mobile Manager system information
      properties:
        version:
          type: string
          description: TMM application version
        apiPort:
          type: integer
          description: REST API port number
        v1SocketPort:
          type: integer
          description: WebSocket port for v1 basic position stream
        v2SocketPort:
          type: integer
          description: WebSocket port for v2 extended position stream (registered apps)
        receiverConnected:
          type: boolean
          description: Whether a GNSS receiver is currently connected
        platform:
          type: string
          enum: [Android, iOS]
          description: Platform TMM is running on

    PositionStreamResponse:
      type: object
      description: Response containing WebSocket port for position streaming
      required: [port]
      properties:
        port:
          type: integer
          description: WebSocket port to connect to for position stream
        format:
          type: string
          description: Position format version that will be streamed

    ReceiverInfo:
      type: object
      description: Connected GNSS receiver information
      properties:
        model:
          type: string
          description: Receiver model name (e.g., R12i, Catalyst DA2)
        serialNumber:
          type: string
          description: Receiver serial number
        firmwareVersion:
          type: string
          description: Receiver firmware version
        connectionType:
          type: string
          enum: [Bluetooth, USB, WiFi, Internal]
          description: Connection method to the receiver

    ReceiverStatus:
      type: object
      description: Current GNSS receiver status
      properties:
        connected:
          type: boolean
        batteryLevel:
          type: integer
          description: Battery percentage (0-100)
        gnssSignalStrength:
          type: string
          enum: [None, Poor, Fair, Good, Excellent]
        trackingGnss:
          type: boolean
          description: Whether receiver is actively tracking GNSS signals

    CorrectionsStatus:
      type: object
      description: GNSS correction service status
      properties:
        type:
          type: string
          enum: [None, SBAS, RTX, RTK, NTRIP, DGNSS]
          description: Active correction type
        status:
          type: string
          enum: [Disconnected, Connecting, Connected, Converging, Active]
        accuracy:
          type: string
          description: Achievable accuracy with current corrections
        provider:
          type: string
          description: Correction service provider name

    CorrectionsConfig:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [RTX, RTK, SBAS, NTRIP, None]
          description: Correction service type to configure
        ntripHost:
          type: string
          description: NTRIP caster host (required for NTRIP type)
        ntripPort:
          type: integer
          description: NTRIP caster port
        ntripMountpoint:
          type: string
          description: NTRIP mountpoint
        ntripUsername:
          type: string
        ntripPassword:
          type: string

    CatalystLicense:
      type: object
      description: Trimble Catalyst positioning accuracy license
      properties:
        id:
          type: string
          description: License identifier
        type:
          type: string
          enum: [Decimeter, Centimeter, Sub-Foot, Sub-Meter]
          description: Accuracy level provided
        status:
          type: string
          enum: [Available, Active, Expired]
        expiresAt:
          type: string
          format: date-time

    PositionInfoV2:
      type: object
      description: >-
        Extended GNSS position message streamed via WebSocket v2 connection.
        Available only to registered applications.
      properties:
        latitude:
          type: number
          format: double
          description: Latitude in decimal degrees (WGS84)
        longitude:
          type: number
          format: double
          description: Longitude in decimal degrees (WGS84)
        altitude:
          type: number
          format: double
          description: Height above ellipsoid in meters
        speed:
          type: number
          format: float
          description: Ground speed in meters per second
        bearing:
          type: number
          format: float
          description: Direction of travel in degrees from north (clockwise)
        satellites:
          type: integer
          description: Number of satellites tracked
        hrms:
          type: number
          format: float
          description: Horizontal Root Mean Square accuracy in meters
        vrms:
          type: number
          format: float
          description: Vertical Root Mean Square accuracy in meters
        pdop:
          type: number
          format: float
          description: Position Dilution of Precision
        hdop:
          type: number
          format: float
          description: Horizontal Dilution of Precision
        vdop:
          type: number
          format: float
          description: Vertical Dilution of Precision
        diffStatus:
          type: integer
          description: "Solution type: 1=Autonomous, 2=DGPS, 4=Fixed, 5=Float"
        timestamp:
          type: string
          format: date-time
          description: GNSS fix timestamp (UTC)
        satelliteView:
          type: array
          items:
            $ref: '#/components/schemas/SatelliteInfo'
        imuOrientation:
          $ref: '#/components/schemas/ImuOrientation'
        referenceFrame:
          $ref: '#/components/schemas/ReferenceFrame'

    PositionInfoV1:
      type: object
      description: Basic GNSS position message streamed via WebSocket v1 connection.
      properties:
        latitude:
          type: number
          format: double
          description: Latitude in decimal degrees (WGS84)
        longitude:
          type: number
          format: double
          description: Longitude in decimal degrees (WGS84)
        altitude:
          type: number
          format: double
          description: Height above ellipsoid in meters
        speed:
          type: number
          format: float
          description: Ground speed in meters per second
        bearing:
          type: number
          format: float
          description: Direction of travel in degrees
        satellites:
          type: integer
        accuracy:
          type: number
          format: float
          description: Position accuracy in meters
        diffStatus:
          type: integer
          description: "Solution type: 1=Autonomous, 2=DGPS, 4=Fixed, 5=Float"
        timestamp:
          type: string
          format: date-time

    SatelliteInfo:
      type: object
      description: Per-satellite tracking information
      properties:
        id:
          type: integer
          description: Satellite PRN or ID
        elevation:
          type: integer
          description: Elevation angle in degrees (0-90)
        azimuth:
          type: integer
          description: Azimuth angle in degrees (0-360)
        snr:
          type: number
          format: float
          description: Signal-to-Noise Ratio in dB-Hz
        used:
          type: boolean
          description: Whether satellite is used in the position solution
        gnssSystem:
          type: string
          enum: [GPS, GLONASS, Galileo, BeiDou, QZSS, SBAS]
          description: GNSS constellation

    ImuOrientation:
      type: object
      description: IMU orientation data (v2 only, select receivers)
      properties:
        pitch:
          type: number
          format: float
          description: Pitch angle in degrees
        roll:
          type: number
          format: float
          description: Roll angle in degrees
        yaw:
          type: number
          format: float
          description: Yaw angle in degrees
        aligned:
          type: boolean
          description: Whether IMU is aligned with receiver

    ReferenceFrame:
      type: object
      description: Coordinate reference frame information (v2 only)
      properties:
        sourceFrame:
          type: string
          description: Source reference frame (e.g., WGS84, ITRF2014)
        targetFrame:
          type: string
          description: Target reference frame after transformation
        epoch:
          type: number
          format: float
          description: Reference epoch for the transformation