Publication Flow

This is a step-by-step guide to connecting a publisher application to the Haptics server and transmitting signals. It assumes your device is already linked to a Melody account.

1. Obtain an authentication token

Request a short-lived authentication token and server endpoint from the App Publisher Auth endpoint (see the API Reference).

curl -X POST -H 'Content-Type: application/json' \
  https://api.getmelody.io/api/haptics/auth/publisher/app

The response contains the WebSocket endpoint and a token to connect with:

{
  "ws_endpoint": "wss://ws.endpoint/haptics",
  "ws_proxy_endpoint": "wss://ws.endpoint/haptics",
  "token": "eyJ0eX..."
}

ws_proxy_endpoint is deprecated — use ws_endpoint.

2. Connect and authenticate

Connect to the Haptics server over WebSocket and send a HapticFrame carrying a Protobuf Auth message. Open the connection:

dialer := websocket.Dialer{
	TLSClientConfig: &tls.Config{},
}

conn, _, err := dialer.Dial("wss://ws.endpoint/haptics", nil)

Send the authentication frame:

authProto := &entities.Auth{
	JwtToken: token, // token from step 1
}

bytes, err := proto.Marshal(authProto)

authFrame := &protocol.HapticFrame{
	Type: entities.FrameType_SUBSCRIPTION,
	Data: bytes,
}

err = authFrame.WriteFrame(c.stream)

3. Handle TimeSync

Echo TIME_SYNC frames back so clients can control the quality of the stream, and react to CONNECTION_INFO events.

for {
	dataFrame, err := protocol.ReadNextFrame(c.stream)

	switch dataFrame.Type {
	// Echo the system TIME_SYNC event back
	case entities.FrameType_TIME_SYNC:
		dataFrame.WriteFrame(c.stream)

	// Adjust internal algorithms using connection info
	case entities.FrameType_CONNECTION_INFO:
		// TODO: your logic

	default:
	}
}

4. Submit signals

Build a HapticSignal from one or more DeviceCommands, marshal it, wrap it in a SIGNAL frame, and write it to the stream.

command := &entities.DeviceCommand{
	Time:    1234567890, // milliseconds
	Channel: 1,
	Pos:     1234, // [0..10000)
}

signalProto := &entities.HapticSignal{
	Commands: []*entities.DeviceCommand{command},
}

bytes, err := proto.Marshal(signalProto)

signalFrame := &protocol.HapticFrame{
	Type: entities.FrameType_SIGNAL,
	Data: bytes,
}

err = signalFrame.WriteFrame(c.stream)

This connects a publisher to the Haptics server, authenticates it, and transmits signals to subscribers. To receive signals instead, see the Subscription Flow.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Publication Flow

1. Obtain an authentication token

2. Connect and authenticate

3. Handle TimeSync

4. Submit signals

​1. Obtain an authentication token

​2. Connect and authenticate

​3. Handle TimeSync

​4. Submit signals

1. Obtain an authentication token

2. Connect and authenticate

3. Handle TimeSync

4. Submit signals