Connect your cricket scoring app to the Clubs Master Recorder App via Bluetooth Low Energy (BLE)

Table of Contents

1. Overview
2. Connection Setup
3. Data Format
4. Field Reference
5. Code Examples
6. Best Practices
7. Troubleshooting

Overview

The Recorder App receives live cricket score data via Bluetooth Low Energy (BLE) and displays it as an overlay during video recording. Any cricket scoring app can integrate by:

1. Acting as a BLE Peripheral (GATT Server)
2. Advertising with specific service UUIDs
3. Sending JSON score packets via BLE notifications

Architecture:

┌─────────────────────┐         BLE         ┌─────────────────────┐
│  Your Scoring App   │ ──────────────────▶ │   Recorder App      │
│  (BLE Peripheral)   │   JSON Packets       │   (BLE Central)     │
└─────────────────────┘                      └─────────────────────┘

Connection Setup

BLE Service Configuration

Your app must advertise as a BLE peripheral with one of these profiles:

Profile 1: ScoreController (Recommended)

Parameter	Value
Device Name	Must start with ScoreController
Service UUID	6E400001-B5A3-F393-E0A9-E50E24DCCA9E
Characteristic UUID	6E400002-B5A3-F393-E0A9-E50E24DCCA9E
Characteristic Properties	NOTIFY, READ

Connection Flow

1. Your app starts advertising with the above UUIDs
2. Recorder App scans for devices with matching names/UUIDs
3. User selects your device from the list
4. Connection is established
5. Your app sends score updates via BLE notifications

---

Data Format

Packet Structure

Send cricket scores as compact JSON via BLE characteristic notifications.

Minimal Packet (Required Fields)

{
  "i": 1,
  "r": 50,
  "w": 3,
  "o": "10.2"
}

Full Packet (All Fields)

{
  "seq": 15,
  "i": 1,
  "r": 125,
  "w": 4,
  "o": "15.3",
  "t": 180,
  "rr": 8.33,
  "mo": 20,
  "bt": "Team A",
  "bwt": "Team B",
  "bats": [
    { "name": "J. Smith", "score": 67, "isStriker": true },
    { "name": "M. Jones", "score": 42, "isStriker": false }
  ],
  "ls": ["4", "0", "1", "W", "2", "6"],
  "type": "cricket",
  "match": "Final Match",
  "venue": "Main Ground"
}

Packet Size Limits

Limit	Value	Notes
Maximum packet size	1024 bytes	Per transmission
BLE MTU	20-512 bytes	Varies by device
Recommended	< 200 bytes	For reliability

Note: For packets larger than device MTU, the app automatically buffers and reassembles fragmented transmissions.

Field Reference

Core Score Fields

Field	Aliases	Type	Required	Description
i	innings, inningsNumber	number	✅	Current innings (1 or 2)
r	runs	number	✅	Total runs scored
w	wickets	number	✅	Wickets fallen (0-10)
o	overs	string	✅	Overs bowled as “O.B” format

Target & Chase Fields

Field	Aliases	Type	Required	Description
t	target, targetScore, target_runs	number	❌	Target score for 2nd innings
fi	firstInnings, firstInningsRuns, first_innings_runs	number	❌	First innings total (alternative to target)

Match Details

Field	Aliases	Type	Required	Description
rr	runRate	number	❌	Current run rate (auto-calculated if not sent)
mo	maxOvers, totalOvers	number	❌	Maximum overs in match (e.g., 20, 50)
bt	leftTeam, home	string	❌	Batting team name
bwt	rightTeam, away	string	❌	Bowling team name
type	–	string	❌	Sport type (always “cricket”)
match	–	string	❌	Match name/title
venue	–	string	❌	Venue/ground name

Batsmen Data

Field	Aliases	Type	Required	Description
bats	batsmen	array	❌	Current batsmen (see formats below)
bn	batsmenNames	array	❌	Alternative batsmen format

Batsmen Format 1: Object Array (Recommended)

"bats": [
  { "name": "J. Smith", "score": 67, "isStriker": true },
  { "name": "M. Jones", "score": 42, "isStriker": false }
]

Batsmen Format 2: String Array (Legacy)

"bats": ["* J. Smith 67", "M. Jones 42"]

Use * prefix to indicate striker

Ball Notation

Symbol	Alternatives	Meaning	Display Color
W	wkt, wd, Wk	Wicket	Red
0	dot	Dot ball	Gray
1	–	Single	Light Green
2	–	Two runs	Light Green
3	–	Three runs	Light Green
4	–	Four (boundary)	Green
6	–	Six (boundary)	Dark Green
B	lb	Byes/Leg-byes	Orange
-	–	Unknown/Missing	Gray

Example:

"ls": ["4", "0", "1", "W", "2", "6"]