The API Heartbeat periodically announces a PIXERA system and its configured Native API access points over UDP. Other PIXERA systems can receive the same heartbeat to discover the sender and monitor whether it is still available.

Typical use cases include:

• Discovering PIXERA systems on a control network
• Finding the Native API protocols and ports offered by a system
• Tracking remote PIXERA systems as Discovered or Lost
• Including the current state of all Live Systems known to the sender

The heartbeat uses JSON/UDP and is sent approximately once per second.

Configuration in PIXERA

1. Open Settings.
2. Select the API sub-tab.
3. Expand Heartbeat.
4. Select the network Adapter that should send and receive heartbeat traffic.
5. Enter the destination IP and Port.
6. Make sure Mute is disabled.
7. Optional: Enable Include All Live Systems in Heartbeat to append Live System details to the payload.

The heartbeat protocol is fixed to JSON/UDP.

Destination IP: Unicast or Multicast

The Destination IP determines who receives the heartbeat and, for multicast, which group PIXERA joins to receive heartbeats from other systems.

PIXERA recognizes every IPv4 address from 224.0.0.0 through 239.255.255.255 as multicast. For a private installation network, use an address from the administratively scoped 239.0.0.0/8 range. Avoid addresses in 224.0.0.0/24, because this range is reserved for local network control protocols.

For example, a group of PIXERA systems can use:

• Destination IP: 239.255.42.1
• Port: 1500
• Adapter: The local adapter connected to the control network

Configure the same multicast destination IP and port on every participating system. Each system sends to the group and listens for the other members on that group and port. The systems may have different local adapter IPs, but every selected adapter must be able to reach the same multicast network.

Changing only the port does not create a separate multicast group, but receivers still need to use the same group and port to exchange heartbeat data. Likewise, systems using different multicast destination IPs do not discover one another even when the port is identical.

Multicast Network Requirements

• Multicast must be enabled on the selected network adapters and permitted by the operating-system firewall.
• Switches with IGMP snooping must forward the selected group to all participating ports.
• Routed multicast requires corresponding multicast routing in the network infrastructure. For a simple setup, keep all participants in the same local network.
• External clients must join the configured multicast group on the correct local adapter before they can receive its datagrams.

Tip

Use one dedicated multicast group and port for each independent PIXERA installation. This prevents unrelated systems on the same network from appearing in the remote heartbeat list.

Applying Changes

Restart PIXERA after changing API or heartbeat settings to ensure that the network connections and the advertised API access information are rebuilt from the current configuration.

How the Heartbeat Works

The configured heartbeat connection sends and receives on the same UDP port. Each PIXERA heartbeat contains:

• One protocol entry for every configured API Access connection whose port is not 0
• One self entry that identifies the sending PIXERA system
• Optionally, one liveSystemHeartbeats entry containing the Live Systems known to the sender

PIXERA uses the IP in the self entry to identify a remote system. A heartbeat is ignored when that IP is empty or matches the receiving system's own API adapter IP.

The API access information is an announcement of the configured interfaces. The heartbeat itself is not a JSON-RPC request and does not return a response.

Packet Format

Although the payload is JSON, a heartbeat datagram does not begin directly with [ or {. PIXERA prefixes the UTF-8 JSON payload with its standard 8-byte packet header.

Attention

A receiver must remove the 8-byte header before parsing the JSON. Attempting to parse the complete UDP datagram as JSON will fail.

JSON Payload

The decoded payload is a JSON array. A heartbeat with Live System information can look like this:

[
  {
    "type": "protocol",
    "ip": "",
    "port": 1400,
    "protocol": "JSON/TCP"
  },
  {
    "type": "protocol",
    "ip": "",
    "port": 8080,
    "protocol": "HTTP/TCP"
  },
  {
    "type": "self",
    "ip": "192.168.10.20"
  },
  {
    "type": "liveSystemHeartbeats",
    "heartbeats": [
      {
        "ip": "192.168.10.20",
        "name": "Local",
        "isLocal": true,
        "state": "Engine Opened"
      },
      {
        "ip": "192.168.10.21",
        "name": "Render-01",
        "isLocal": false,
        "state": "Engine Opened"
      }
    ]
  }
]

The order of JSON object properties should not be used when parsing the payload.

protocol Entry

self Entry

liveSystemHeartbeats Entry

This entry is included only when Include All Live Systems in Heartbeat is enabled and Live System information is available.

Possible Live System state strings are:

• None
• New
• Requested Info
• Known
• Engine Opening
• Engine Opened
• Engine Open Failed
• Engine Closing
• Engine Closed
• Engine Closing For Restart
• Engine Closed For Restart
• Lost
• Taking Over
• MU Project Source
• MU Project Receiver
• MU Not Participating
• Undefined

These values describe Live Systems managed by the sender. They are separate from the remote heartbeat tracking states described below.

Accessing Session API commands

Pixera also receives the heartbeat signals from other systems; these can also be used within the API. The heartbeat tracker is available through three actions in Pixera.Session.

remoteSystemStateChange(string ip, string state)

This callback action runs whenever a tracked remote system changes between Discovered and Lost.

Use this action in PIXERA Control when logic should react immediately to a remote heartbeat state change.

string[] getRemoteSystemIps()

Returns all remote system IPs known to the heartbeat tracker. The result includes systems whose current state is Lost.

Control example:

local ips = Pixera.Session.getRemoteSystemIps()

JSON-RPC example over a request/response-capable API connection:

{"jsonrpc":"2.0","id":1,"method":"Pixera.Session.getRemoteSystemIps"}

Example response:

{"jsonrpc":"2.0","id":1,"result":["192.168.10.20","192.168.10.30"]}

string getRemoteSystemState(string ip)

Returns Discovered, Lost, or unknown for the supplied IP.

Control example:

local state = Pixera.Session.getRemoteSystemState("192.168.10.20")

JSON-RPC example over a request/response-capable API connection:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "Pixera.Session.getRemoteSystemState",
  "params": {
    "ip": "192.168.10.20"
  }
}

Example response:

{"jsonrpc":"2.0","id":2,"result":"Discovered"}

Use JSON/TCP or JSON/TCP (dl) when calling the two get actions externally. JSON/UDP does not provide the reliable return-value handling required for these queries.

Troubleshooting

No Heartbeat Is Received

• Verify that Mute is disabled.
• Make sure the heartbeat port is not 0.
• Check that sender and receiver use the same UDP port.
• For multicast, check that all systems use the same multicast group and the correct local adapter.
• Check the operating-system firewall and managed network configuration.

The Datagram Is Not Valid JSON

Remove the leading 8-byte pxr1 packet header before decoding the UTF-8 JSON payload.

No Remote System Appears

• Confirm that the received array contains a self entry with a non-empty IP.
• Make sure the remote self.ip does not equal the local API adapter IP.
• Check that the heartbeat connection is configured to receive on the selected adapter and port.

A Remote System Changes to Lost

PIXERA marks a remote system as Lost after more than five consecutive checks without a valid heartbeat. Check for UDP packet loss, firewall rules, multicast filtering, an incorrect adapter, or a mismatch between the configured ports.

Live System Details Are Missing

Enable Include All Live Systems in Heartbeat and verify that the Live Systems are visible to the sending PIXERA instance. The liveSystemHeartbeats entry is optional and may be absent when no Live System information is available.

Related Articles

• Pixera Native API Introduction
• API Commands
• API documentation files

PIXERA 26.2 | 21 September 2026 | J.B.