Hyperion
    Hyperion
    • JSON-RPC API Introduction
    • JSON-API Commands Overview
    • Connect to Hyperion
    • Components & Priorities
    • Hyperion API
      • Authorization
        • API Authentication - Introduction
        • createToken
        • renameToken
        • deleteToken
        • getTokenlist
        • tokenRequired
        • adminRequired
        • newPasswordRequired
        • requestToken
        • newPassword
        • answerRequest
        • getPendingTokenRequests
        • login
        • logout
      • Information
        • getSystemInformation
        • getSubscriptionInformation
        • getServerInformation
        • getImageSnapshot
        • getLedsSnapshot
      • Controls
        • Input Controls
          • setColor
          • setEffect
          • setImage
          • clear
          • clearAll
          • selectSource
        • Output Controls
          • adjustColors
          • setLedMapping
          • setVideomode
        • Subscription Controls
          • liveImageStream
          • liveLedColorStream
        • Operational Controls
          • setComponentState
          • setInstanceState
          • switchInstance
          • setSystemState
          • setSubscriptions
      • Configuration
        • createInstance
        • deleteInstance
        • renameInstance
        • getConfiguration
        • updateConfiguration
        • restoreConfiguration
        • getSchemas

    Connect to Hyperion

    Ways of connecting to Hyperion#

    Hyperion currently supports multiple connection mechanisms: TCP Socket ("JSON Server"), WebSocket and HTTP/S.
    TIP
    You can automatically discover Hyperion servers! See Detect Hyperion

    TCP Socket#

    This is a "raw" connection, you can send and receive line-separated JSON from the server (default port: 19444). This is also known as the "JSON Server".

    WebSocket#

    This is part of the Hyperion webserver (default port ws: 8090, for wss: 8092).
    You send and receive JSON commands via Websocket.
    Only TEXT mode is supported. Read more about Websockets at Websocket.

    HTTP/S JSON#

    HTTP requests can also be sent to the webserver (default port: 8090, for HTTPS: 8092).
    Send a HTTP/S POST request along with a properly formatted JSON message in the body to the (example) url: http://IpOfDevice:WebserverPort/json-rpc
    TIP
    If you get a "No Authorization" response, you need to create an Authorization token.
    HTTP/S Restrictions
    Please note that not all JSON-RPC commands are supported via HTTP/S.
    To check, if a command is supported via HTTP/S see an endpoint's documentation or JSON-API Commands Overview

    Detect Hyperion#

    Hyperion announces its services on the network, via mDNS and SSDP.

    SSDP#

    SimpleServiceDiscoveryProtocol (SSDP) is the discovery subset of UPnP. The implementation is lighter than mDNS as it just needs a UDP Socket without any further dependencies.

    SSDP-Client Library#

    Here are some example client libraries for different programming languages (many others available):
    NodeJS
    Java

    Usage#

    With a given SSDP-client library, you can use the following USN / service type:
    urn:hyperion-project.org:device:basic:1
    Some headers from the response will include:
    Location: The URL of the webserver
    USN: The unique id for this Hyperion instance, it will remain the same after system restarts or Hyperion updates
    HYPERION-FBS-PORT: The port of the FlatBuffer server
    HYPERION-JSS-PORT: The port of the JSON-API server
    HYPERION-NAME: The user defined name for this server
    As the data changes (e.g. network adapter IP address change), new updates will be automatically announced.

    Multicast DNS (mDNS)#

    Hyperion services are detectable through mDNS.
    mDNS is also known as Zeroconf, Apple Bonjour or Avahi.
    Hyperion publishes the following services:
    _http._tcp: Hyperion Webserver (HTTP + Websocket)
    _https._tcp: Hyperion Webserver (HTTPS + Websocket Secure)
    _hyperiond-json._tcp: Hyperion JSON-API Server (TcpSocket)
    _hyperiond-flatbuf._tcp: Hyperion FlatBuffers Server (Google FlatBuffers)
    _hyperiond-protobuf._tcp: Hyperion Protocol Buffers Server (Google Protocol Buffers)
    You get the mDNS service name, IP address and service port.
    As this works realtime, i.e. you can always have an up to date list of available Hyperion servers.
    Service - TXT RECORD
    Each published entry contains at least the following data in the txt field:
    id: A static, unique id to identify a Hyperion instance.
    version: Hyperion's version.

    Test Clients#

    There are several clients available for testing like the avahi-browse a
    commandline tool for Ubuntu/Debian. Example command
    avahi-browse.jpg
    Modified at 2025-05-19 20:20:47
    Previous
    JSON-API Commands Overview
    Next
    Components & Priorities
    Built with