Communication WebSockets

WebSockets give you a permanent, bidirectional connection over TCP - between two microcontrollers, or between a microcontroller and a web page or any other WebSocket client. They are a good fit if a browser should receive audio via JavaScript, or if a device both sends and receives audio and control messages over one connection. See Communication for the general considerations.

Library

The WebSocket support is based on arduinoWebSockets by Links2004 - install it.

Sending: WebSocketOutput

WebSocketOutput (AudioTools/Communication/WebSocketOutput.h) is an AudioOutput that sends each write() as one binary WebSocket message. It works with a WebSocketsClient - it sends to its server - and with a WebSocketsServer - it sends to all connected clients:

WebSocketsClient webSocket;
WebSocketOutput out(webSocket);  // or WebSocketOutput out(webSocketServer);

From client-as-source/client, a client that sends a sine tone to a server:

#include <WebSocketsClient.h>  // https://github.com/Links2004/arduinoWebSockets
#include <WiFiMulti.h>
#include "AudioTools.h"
#include "AudioTools/Communication/WebSocketOutput.h"

WiFiMulti WiFiMulti;
WebSocketsClient webSocket;
WebSocketOutput out(webSocket);
AudioInfo info(44100, 2, 16);
SineGenerator<int16_t> sineWave(32000);
GeneratedSoundStream<int16_t> sound(sineWave);
Throttle throttle(out);
StreamCopy copier(throttle, sound);

void setup() {
  WiFiMulti.addAP("ssid", "password");
  while (WiFiMulti.run() != WL_CONNECTED) delay(100);
  WiFi.setSleep(false);
  webSocket.begin("192.168.1.34", 81, "/");  // server address, port, URL
  webSocket.setReconnectInterval(5000);
  sineWave.begin(info, N_B4);
  throttle.begin(info);  // WebSockets are asynchronous: limit the sending to the audio rate
}

void loop() {
  webSocket.loop();
  if (webSocket.isConnected()) copier.copy();
}

Receiving

The receiving side gets the audio in the WebSocket event callback and writes it to the output. From client-as-source/server:

#include <WebSocketsServer.h>
#include "AudioTools.h"
#include "AudioTools/AudioLibs/AudioBoardStream.h"

WebSocketsServer webSocket(81);
AudioInfo info(44100, 2, 16);
AudioBoardStream i2s(AudioKitEs8388V1);

void webSocketEvent(uint8_t num, WStype_t type, uint8_t* payload, size_t length) {
  if (type == WStype_BIN) i2s.write(payload, length);
}

void setup() {
  // ... connect WiFi
  webSocket.begin();
  webSocket.onEvent(webSocketEvent);
  auto cfg = i2s.defaultConfig(TX_MODE);
  cfg.copyFrom(info);
  i2s.begin(cfg);
}

void loop() { webSocket.loop(); }

The server-as-source examples do the opposite: the server sends, and the client plays.

Things to consider

• Throttling: the WebSocket library sends asynchronously and doesn't slow a fast source down - use a Throttle for a generator or a file. A source at the audio rate (microphone, I2S) doesn't need it.
• The audio format is not transmitted - sender and receiver must agree on it, or send it in a text message first.
• Bandwidth: like all TCP connections, WebSockets can't send faster than the network: 44.1 kHz stereo PCM needs 1.4 Mbit/s - consider a codec (see Communication).
• Browser: in JavaScript, receive the binary messages as ArrayBuffer and play them with the Web Audio API.
• Sending to one client of a server: by default a WebSocketsServer broadcasts to all connected clients; with setTargetNo(clientNo) the data is sent to one client only.
• The examples are in the sandbox: they are less tested than the other examples.