Skip to main content
V5 - Java Server DocumentationThese docs are for Java Server V5 Only. For all other languages and platforms, continue using SDK v4 until V5 support is available.
You can read more about the various transports that Ditto uses in Mesh Networking.
Although Ditto automatically attempts to connect to other instances on the Local Area Network (LAN), Bluetooth Low Energy (LE), and Apple Wireless Direct Link (AWDL), supplying a custom instance of the DittoTransportConfig does not enable this feature by default. Rather, you manually enable peer-to-peer connections using EnableAllPeerToPeer().This is only true if you provide a custom instance of the DittoTransportConfig object. If you do not provide a custom instance, Ditto will automatically enable all peer-to-peer transports by default.The best way to ensure that you are using the correct transport configuration is to use the updateTransportConfig API to update the DittoTransportConfig object. This will ensure that you are using the correct transport configuration and that you are not missing any transports.

​
Enabling and Disabling Transports

When a new Ditto instance is created, a default transport configuration is supplied that enables all peer-to-peer transports by default. You can control which transports are enabled or disabled by updating the DittoTransportConfig object.
Changing the transport configuration via the updateTransportConfig API after sync has been started will instantly apply the changes without the need to manually stop and start sync.
ditto.updateTransportConfig(transportConfig -> {
  //Or enable/disable each transport separately

  //BluetoothLe
  transportConfig.getPeerToPeer().getBluetoothLe().setEnabled(true);
  //Local Area Network
  transportConfig.getPeerToPeer().getLan().setEnabled(true);
  //Wifi Aware
  transportConfig.getPeerToPeer().getWifiAware().setEnabled(true);

});
try {
    ditto.startSync();
} catch(DittoError error) {
    // handle error
}

​
Syncing with Ditto Server / WebSocket Connections

To sync with the Ditto Server or to initialize a WebSocket connection, you need to add a websocketURL to the DittoTransportConfig object. You can do this by calling updateTransportConfig and adding the websocketURL to the connect.websocketURLs array.
Using the updateTransportConfig API to remove all webSocketURLs from the connect object will disable sync with the Ditto Server instantly without needing to call stop and start sync on the Ditto instance.
ditto = Ditto(
  identity: DittoIdentity.onlinePlayground(
    appID: "REPLACE_ME_WITH_YOUR_APP_ID",
    token: "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN",
    enableDittoCloudSync: false, // This is required to be set to false to use the correct URLs
    customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_AUTH_URL")
  )
)

ditto.updateTransportConfig { transportConfig in
  // Set the Ditto Websocket URL
  transportConfig.connect.webSocketURLs.insert("wss://REPLACE_ME_WITH_YOUR_WEBSOCKET_URL")
}

// Disable DQL strict mode so that collection definitions are not required in DQL queries
try await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")

do {
  try ditto.startSync()
} catch {
  print(error.localizedDescription)
}

​
Configuring Additional Settings

If you need additional connection configurations for the current Ditto instance, configure it to listen for connections on a specific port and to connect to remote instances using a host (IP) and port:

​
Connecting to Remote Small Peers


ditto.updateTransportConfig(transportConfig -> {
   // Connect explicitly to a remote devices
  transportConfig.getConnect().setTcpServers(Sets.newHashSet("135.1.5.5:12345", "185.1.5.5:12345"));
});
try {
    ditto.startSync();
} catch(DittoError error) {
    // handle error
}

​
Listening for Connections

For some use cases, you can configure a Ditto instance to accept incoming TCP connections from remote peers at a specific IP address and port. This is different from the automatic peer-to-peer discovery that happens by default. Use this when you want your device to act as a connection hub that other devices can connect to directly, rather than relying solely on automatic discovery mechanisms like mDNS or Bluetooth. 

ditto.updateTransportConfig(transportConfig -> {
  // Listen for incoming connections on port 4000
  DittoListen listen = new DittoListen();
  DittoTcpListenConfig tcpListenConfig = new DittoTcpListenConfig();
  // By default Tcp Enabled is false, be sure to set it to true.
  tcpListenConfig.setEnabled(true);
  // if you want to listen on localhost, most likely you will use 0.0.0.0
  // do not use "localhost" as a string
  tcpListenConfig.setInterfaceIp("0.0.0.0");
  tcpListenConfig.setPort(4000);
  transportConfig.setListen(listen.setTcp(tcpListenConfig));
});
try {
    ditto.startSync();
} catch(DittoError error) {
    // handle error
}

​
Combining Multiple Transports

A reminder when a new Ditto instance is created, a default transport configuration is supplied that enables all peer-to-peer transports by default. You can combine multiple transports to suit your needs. For example, you can listen for incoming connections on a specific port and connect to remote devices. 

ditto.updateTransportConfig(transportConfig -> {
  // 1. Listen for incoming connections on port 4000
  DittoListen listen = new DittoListen();
  DittoTcpListenConfig tcpListenConfig = new DittoTcpListenConfig();
  tcpListenConfig.setEnabled(true);
  tcpListenConfig.setInterfaceIp("0.0.0.0");
  tcpListenConfig.setPort(4000);
  transportConfig.setListen(listen.setTcp(tcpListenConfig));

  // 2. Connect explicitly to remote devices
  transportConfig.getConnect().setTcpServers(Sets.newHashSet("135.1.5.5:12345", "185.1.5.5:12345"));
});
try {
    ditto.startSync();
} catch(DittoError error) {
    // handle error
}

​
Monitoring Conditions

// Setting up inside an Activity
ditto.startSync();

// Now you can observe real time changes to the transport conditions:
public class MainActivity extends AppCompatActivity implements DittoCallback {
    @Override
    public void transportConditionDidChange(@NotNull DittoTransportCondition condition, @NotNull DittoConditionSource transportId) {
        String toastText = null;
        if (condition == DittoTransportCondition.BleDisabled) {
            toastText = "BLE disabled";
        } else if (condition == DittoTransportCondition.NoBleCentralPermission) {
            toastText = "Permission missing for BLE";
        } else if (condition == DittoTransportCondition.NoBlePeripheralPermission) {
            toastText = "Permission missing for BLE";
        }

        if (toastText != null) {
            String finalToastText = toastText;
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    Toast.makeText(MainActivity.this, finalToastText, Toast.LENGTH_LONG).show();
                }
            });
        }
    }
}