WebRTC Signaling layer

The protocol specification is only relevant as background information or if you want to make your own Nabto WebRTC Signaling protocol implementation, e.g. for a currently unsupported target platform or app framework. For most applications, the standard implementations provided by Nabto through the available SDKs are sufficient - see the Applications guide.

The Nabto WebRTC Signaling protocol is split into four layers, this document is about the WebRTC Signaling layer:

  • WebRTC Signaling layer
  • Signing layer
  • Reliability layer
  • Routing layer

This is the layer on which WebRTC signaling is actually performed. This section describes the format that the Nabto provided MessageTransport implementations use. These are in turn used in the Nabto provided examples.

If the application needs to use another format, this can be changed as long as it is changed both on the client and the device side. This protocol layer should be sufficient to handle WebRTC connection establishment for most cases. Any actual application feature communications (eg. remote device configuration) should be done using a WebRTC datachannel after the connection is established and NOT using the signaling channel.

The WebRTCSignaler messages are JSON documents which are sent as the message through the Signing layer.

The WebRTC Signaling layer defines four message types:

  • SETUP_REQUEST: First message sent on a channel from a client to the device.
  • SETUP_RESPONSE: First message sent on a channel from the device to a client.
  • DESCRIPTION: A message containing a WebRTC description
  • CANDIDATE: A message containing a WebRTC ICE candidate

SETUP_REQUEST

First message sent from a client to create channel state in the device and to trigger the device to send a SETUP_RESPONSE containing ICE server configuration the client can use when creating its RTC peer connection.

{
  type: "SETUP_REQUEST",
}

SETUP_RESPONSE

First message sent from a device as response to a SETUP_REQUEST received from a client. This response includes ICE server configurations received from the Signaling service in case the client is not able to make an authorized HTTP request to the Signaling service and retrieve TURN credentials itself.

{
  type: "SETUP_RESPONSE",
  iceServers?: {
    credential?: string,
    urls: Array<string>,
    username?: string,
  }
}

DESCRIPTION

When the WebRTC library needs to start a (re-)negotiation, or has created an answer for a received offer, it is sent to the other peer as a Description.

{
  type: "DESCRIPTION",
  description: {
    type: string,
    sdp: string
  }
}

The description field follows the standard description format used in browsers.

CANDIDATE

For WebRTC connections established with the Trickle ICE feature, ICE candidates are sent as they are gathered instead of postponing sending Descriptions until all candidates has been gathered. Such ICE candidates are sent using this message type.

{
  type: "CANDIDATE",
  candidate: {
    candidate: string,
    sdpMid?: string,
    sdpMLineIndex?: number,
    usernameFragment?: string
  }
}

The candidate field follows the standard candidate format used in browsers.