react-native-kepler-udp

UDP socket Turbo Module for React Native on the Kepler platform (Amazon Fire TV devices).

Installation

npm install react-native-kepler-udp

API

import { ReactNativeKeplerUdp } from 'react-native-kepler-udp';

Socket lifecycle

| Method | Description | |---|---| | createSocket(options) | Create a UDP socket. Returns a numeric socket id. | | bind(id, port, address, callback) | Bind the socket to a local port and address. | | close(id, callback) | Close and destroy the socket. | | connect(id, port, address, callback) | Connect the socket to a remote address. | | disconnect(id) | Disconnect a connected socket. |

createSocket options:

| Option | Type | Description | |---|---|---| | type | string | Address family: 'udp4' or 'udp6' | | reuseAddr | boolean | Allow reusing the address | | reusePort | boolean | Allow reusing the port | | ipv6Only | boolean | Restrict to IPv6 only | | recvBufferSize | number | Receive buffer size in bytes | | sendBufferSize | number | Send buffer size in bytes |

Send

send(id: number, base64String: string, port: number, address: string, callback: () => void): void;

Data must be base64-encoded. Use Buffer.from(data).toString('base64') to encode strings.

Receiving messages

addListener(eventType: string): void;
removeListeners(count: number): void;

Messages arrive as native events on the UdpSocketMessage event. Listen via NativeEventEmitter:

import { NativeEventEmitter } from 'react-native';

const emitter = new NativeEventEmitter();

ReactNativeKeplerUdp.addListener('message');

const subscription = emitter.addListener('UdpSocketMessage', (payload) => {
  const { id, data, address, port } = payload;
  const message = Buffer.from(data, 'base64').toString();
  // handle message
});

Multicast

| Method | Description | |---|---| | addMembership(id, multicastAddress, multicastInterface) | Join a multicast group. | | dropMembership(id, multicastAddress, multicastInterface) | Leave a multicast group. | | setMulticastTTL(id, ttl) | Set multicast time-to-live. | | setMulticastLoopback(id, flag) | Enable/disable multicast loopback. | | setMulticastInterface(id, multicastInterface) | Set the outgoing multicast interface. |

Broadcast

| Method | Description | |---|---| | setBroadcast(id, flag) | Enable/disable broadcast on the socket. |

Buffer control

| Method | Description | |---|---| | getRecvBufferSize(id) | Get receive buffer size. | | getSendBufferSize(id) | Get send buffer size. | | setRecvBufferSize(id, size) | Set receive buffer size. | | setSendBufferSize(id, size) | Set send buffer size. |

Reference counting

| Method | Description | |---|---| | ref(id) | Increment reference count (keeps event loop alive). | | unref(id) | Decrement reference count. |

Socket info

| Method | Description | |---|---| | address(id) | Returns { address, family, port } for the bound socket. | | remoteAddress(id) | Returns { address, family, port } for the connected peer. |

Other

| Method | Description | |---|---| | setTTL(id, ttl) | Set unicast time-to-live. |

Example app

An example application is included in the example/ directory. It demonstrates:

• UDP Ping-Pong — Creates two sockets that send PING/PONG messages to each other on loopback.
• Jellyfin Discovery — Broadcasts a discovery message on the local network to find Jellyfin media servers.

cd example
npm install
npm start

Emulator broadcast relay

Android emulators cannot send UDP broadcasts to 255.255.255.255. Use the relay script when testing the Jellyfin Discovery example on an emulator:

python3 scripts/udp_broadcast_relay.py

The app automatically detects emulators and routes traffic through the relay.

Project structure

src/                    # TypeScript source
  index.ts              # Package entry point
  turbo-modules/        # Turbo Module interface
kepler/                 # Native C++ implementation
  turbo-modules/        # Hand-written native code
  turbo-modules/generated/  # Auto-generated spec
  AutoLinkInit.cpp      # Module autolinking entry
example/                # Demo application
test/                   # Jest tests
scripts/                # Helper scripts
CMakeLists.txt          # Native build configuration
react-native.config.js  # Module autolink config

Development

Building

# TypeScript only
npm run build:js

# Debug native build (with kepler CLI)
npm run build:native:debug

# Full release build
npm run build

Testing

npm test

Linting

npm run lint
npm run lint:fix

License

MIT