Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ or system tray (Windows). No phone, no JBL Portable app.
- 🔄 Auto-reconnects, even though JBL speakers rotate their Bluetooth address
- 🖼️ The speaker's photo in its actual color, built in for 17 models
- 🔀 One-click switching when several JBL speakers are nearby
- 🔗 Auracast and stereo pairing: flip a speaker's broadcast on, and choose which half of the pair it plays
- 🔊 Volume and mute, while the speaker is your computer's sound output
- ☕ Keep Awake: stops the speaker's auto power-off while your computer is playing to it (JBL has no setting for this)
- ⚙️ Settings: launch at login, low-battery alerts, update checks
Expand All @@ -50,8 +51,8 @@ or system tray (Windows). No phone, no JBL Portable app.

| Status | Models |
|---|---|
| ✅ Verified | Flip 7, Charge 6, Charge 5 |
| 🟠 Beta | Xtreme 3, Xtreme 4, Go 4, Go 4 Duo, Clip 5, Tuner 3 |
| ✅ Verified | Flip 7, Charge 6, Charge 5, Go 4 |
| 🟠 Beta | Xtreme 3, Xtreme 4, Go 4 Duo, Clip 5, Tuner 3 |
| 🟣 Experimental | Go 5, Grip, Xtreme 5, Boombox 2/3/4, Flip 6, Pulse 5, Flip/Charge Essential 3 SE, older models |

Full list with product IDs: [docs/SUPPORTED_MODELS.md](docs/SUPPORTED_MODELS.md). Both apps share the same
Expand All @@ -61,6 +62,13 @@ on Windows.
Beta and experimental models read battery and EQ safely. Changing their EQ needs **Allow experimental EQ**
(Settings, on both) until someone with that speaker confirms it works.

**Auracast:** on models JBL lists as Auracast-capable (the Go 4, Xtreme 4/5, Boombox 3/4, Clip 5, Charge 6,
Flip 7 and others), the app shows an Auracast switch and, for the portable models, a **Left / Right / Mono**
picker. The two speakers still pair on the hardware: press Auracast on the second one (or bump two Go 4 Duos
together), then connect to each unit in turn and set its half. A Mac cannot be an Auracast source or receiver
(no LE Audio API), so the app only sends the control frames. If a unit stops answering after it
starts broadcasting, press its Auracast button once; the app may not be able to reopen the link.

**Have a beta or experimental model?** Choose **Copy Diagnostics** (Mac: the ••• menu; Windows: right-click
the tray icon) and paste it into a [device report](../../issues/new?template=device-report.yml). It only sends
read-only requests, and it hides your speaker's MAC address and serial number.
Expand Down
40 changes: 32 additions & 8 deletions Sources/JBLControl/Diagnostics.swift
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ import JBLControlKit
/// Builds a Markdown report that's safe to paste into a public GitHub issue.
@MainActor
enum Diagnostics {
/// Three backticks, spelled without the character so the file stays easy to quote.
private static let fence = "\u{60}\u{60}\u{60}"

static func copyReport(_ speaker: SpeakerManager) async {
await speaker.runDiagnosticProbe()
let report = build(speaker)
Expand All @@ -18,35 +21,56 @@ enum Diagnostics {
var lines = ["## JBLControl diagnostics", "", "- App: \(version)", "- macOS: \(os)"]

if let model = speaker.model {
lines.append("- Model: \(model.name) (PID `\(String(format: "%04X", model.productID))`), "
+ "family `\(model.family.rawValue)`, support `\(model.support.label)`")
lines.append("- Model: \(model.name) (PID \(hex(model.productID))), "
+ "family \(model.family.rawValue), support \(model.support.label)")
} else if let pid = speaker.productID {
lines.append("- Model: unknown PID `\(String(format: "%04X", pid))`")
lines.append("- Model: unknown PID \(hex(pid))")
}
lines.append("- Status: \(speaker.status)")
if let firmware = speaker.firmware { lines.append("- Firmware: \(firmware)") }
if let battery = speaker.battery { lines.append("- Battery: \(battery)%\(speaker.isCharging ? " (charging)" : "")") }
if let eq = speaker.eq {
lines.append("- EQ: active `\(String(format: "%02X", eq.activeCategory))`, custom \(speaker.customGains)")
lines.append("- EQ: active \(String(format: "%02X", eq.activeCategory)), custom \(speaker.customGains)")
}
if let linkMode = speaker.linkMode { lines.append("- Link mode: \(linkMode.label)") }
if let channel = speaker.stereoChannel { lines.append("- Stereo channel: \(channel.label)") }
if let role = speaker.role { lines.append("- Link role: \(role.label)") }
if let locked = speaker.stereoLock { lines.append("- Stereo lock: \(locked ? "on" : "off")") }
if let group = speaker.auracastGroup {
var groupLine = "- Group: \(group.type?.label ?? "?") \(group.channel?.label ?? "?")"
if let id = group.groupIDHex { groupLine += " \(id)" }
if let name = group.name { groupLine += " \(name)" }
if let action = group.action { groupLine += ", action \(action)" }
lines.append(groupLine)
}

lines += ["", "### Nearby JBL advertisements", "```"]
lines += ["", "### Nearby JBL advertisements", fence]
for s in speaker.discovered {
lines.append("\(s.model?.name ?? "unknown") pid=\(s.productID.map { String(format: "%04X", $0) } ?? "?") "
lines.append("\(s.model?.name ?? "unknown") pid=\(s.productID.map(hex) ?? "?") "
+ s.advertisement.sorted { $0.key < $1.key }.map { "\($0.key)=\($0.value)" }.joined(separator: " "))
}
lines += ["```", "", "### GATT", "```"] + speaker.gattSummary + ["```", "", "### Traffic (most recent last)", "```"]
lines.append(fence)
if !speaker.infoTokens.isEmpty {
lines += ["", "### Device info tokens", fence]
for (token, value) in speaker.infoTokens.sorted(by: { $0.key < $1.key }) {
lines.append(String(format: "%02X ", token) + Data(value).hex)
}
lines.append(fence)
}
lines += ["", "### GATT", fence] + speaker.gattSummary + [fence, "", "### Traffic (most recent last)", fence]

let start = speaker.traffic.first?.date ?? .now
for entry in speaker.traffic.suffix(80) {
let t = String(format: "%7.2f", entry.date.timeIntervalSince(start))
let arrow = entry.direction == .sent ? "→" : "←"
lines.append("\(t) \(arrow) \(redacted(entry.data).hex)")
}
lines.append("```")
lines.append(fence)
return lines.joined(separator: "\n")
}

private static func hex(_ value: UInt16) -> String { String(format: "%04X", value) }

/// Masks the MAC address (info token 0x48) and serial number (0xC2).
static func redacted(_ data: Data) -> Data {
var b = [UInt8](data)
Expand Down
165 changes: 162 additions & 3 deletions Sources/JBLControl/SpeakerManager.swift
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,27 @@ final class SpeakerManager: NSObject {
private(set) var isCharging = false
private(set) var firmware: String?
private(set) var eq: EQSnapshot?
/// Every info token the speaker has reported, raw: token id to value bytes.
private(set) var infoTokens: [UInt8: [UInt8]] = [:]
/// Link mode from `AA 6B`, or the mode we last asked for: Auracast, PartyBoost or off.
private(set) var linkMode: LinkMode?
/// Token 3C, the older "Play Together" bit. Kept as a fallback for models that don't answer 0x6A.
private(set) var playTogether: Bool?
/// Token 46: this unit's half of a stereo pair.
private(set) var channel: AudioChannel?
/// Role from `AA 6B` / `AA 16`: normal, broadcasting or receiving.
private(set) var role: DeviceRole?
/// Token 49: the chosen half is locked.
private(set) var stereoLock: Bool?
/// Token 4C: the model itself says it supports Auracast.
private(set) var auracastSupportedToken: Bool?
/// Token 45: how many units the speaker believes are linked.
private(set) var linkedDevices: Int?
/// `AA A2`: the stereo/party group this unit is in, when it reports one.
private(set) var auracastGroup: AuracastGroup?
/// The channel we wrote and the speaker ACKed. Token 46 reads back 0 outside a
/// group, so it must not overwrite this.
@ObservationIgnored private var pendingChannel: AudioChannel?
/// Last known custom curve; survives replies that don't carry it.
private(set) var customGains: [Float] = []
private(set) var traffic: [TrafficEntry] = []
Expand All @@ -49,6 +70,32 @@ final class SpeakerManager: NSObject {
var activePreset: EQPreset? { eq.flatMap { e in model?.pickerPresets.first { $0.category == e.activeCategory } } }
var isCustomActive: Bool { eq != nil && eq?.activeCategory == model?.customCategory }
var canWrite: Bool { model.map { !$0.writesNeedOptIn || allowExperimentalWrites } ?? false }
/// Whether this speaker can join an Auracast broadcast, from the model table or its own tokens.
var supportsAuracast: Bool {
if model?.hasAuracast == true || auracastSupportedToken == true { return true }
return linkMode != nil || playTogether != nil
}

/// Whether left/right is ours to choose. AirTouch pairs decide it themselves.
var canSetChannel: Bool { model?.hasStereoChannel ?? (channel != nil) }

/// Auracast (or another multi-speaker mode) is on. Token 3C and the link role are
/// there for firmware that never answers `AA 6A`.
var isAuracastOn: Bool {
if linkMode == .auracast { return true }
if linkMode == .off { return false }
if role == .master || role == .slave { return true }
return playTogether == true
}

/// The channel to show: prefer what the group reply says, fall back to token 46.
var stereoChannel: AudioChannel? { auracastGroup?.channel ?? channel }

/// Another nearby unit of the same model, so the two halves of a pair can be set in turn.
var otherUnit: DiscoveredSpeaker? {
guard let model, model.hasAuracast else { return nil }
return discovered.first { $0.id != activeID && $0.model?.name == model.name }
}
var connectedID: UUID? { status == .connected ? peripheral?.identifier : nil }
/// Advertised name of the speaker currently being connected to.
var connectingName: String? { discovered.first { $0.id == peripheral?.identifier }?.name }
Expand Down Expand Up @@ -131,7 +178,69 @@ final class SpeakerManager: NSObject {

func refresh() {
guard status == .connected else { return }
enqueue([Frame.requestInfo.encoded] + (codec?.readRequests() ?? []))
enqueue([Frame.requestInfo.encoded] + tokenRequests + auracastRequests + (codec?.readRequests() ?? []))
}

/// Group status is only worth asking for on a model that can hold one.
private var auracastRequests: [Data] {
guard model?.hasAuracast == true else { return [] }
if model?.family.usesProtocol4 == true {
return P4Message.get([P4Party.auracastMode, P4Party.channel, P4Party.status,
P4Party.groupType, P4Party.role, P4Party.groupID]).packets
}
return [Frame.requestLinkRole.encoded, Frame.requestAuracastGroup.encoded]
}

/// Tokens we ask for by name: the info burst does not always include them.
private var tokenRequests: [Data] {
[Frame.requestToken(InfoTokenID.auracast).encoded,
Frame.requestToken(InfoTokenID.audioChannel).encoded,
Frame.requestToken(InfoTokenID.stereoLock).encoded,
Frame.requestToken(InfoTokenID.auracastSupport).encoded]
}

/// Turn Auracast on or off (`AA 6A 01 02` / `AA 6A 01 00`), the same switch JBL's app uses.
///
/// It does not create the pair by itself: the two Go 4s join each other on the speakers
/// (the Auracast button on both, or AirTouch on a Duo). This is what flips a unit into
/// broadcast mode so the second one can receive it.
func setAuracast(_ on: Bool) {
guard status == .connected, supportsAuracast, canWrite else { return }
let mode: LinkMode = on ? .auracast : .off
linkMode = mode
if model?.family.usesProtocol4 == true {
enqueue(P4Message.set([(P4Party.auracastMode, [on ? 0x01 : 0x00])]).packets)
} else {
enqueue([Frame.setLinkMode(mode).encoded])
}
}

/// Choose this unit's half of the pair (`AA 15 03 00 46 <0|1|2>`).
func setChannel(_ channel: AudioChannel) {
guard status == .connected, canSetChannel, canWrite else { return }
self.channel = channel
pendingChannel = channel
if model?.family.usesProtocol4 == true {
enqueue(P4Message.set([(P4Party.channel, [channel.rawValue])]).packets)
} else {
enqueue([Frame.setAudioChannel(channel).encoded])
}
}

/// Flip left and right on the unit we're connected to.
func swapChannel() {
setChannel((stereoChannel ?? .mono).swapped)
}

/// Ask for the role and group status again (read-only).
func refreshAuracastGroup() {
guard status == .connected else { return }
enqueue(auracastRequests)
}

/// Ask the speaker to re-send one info token (read-only).
func readToken(_ token: UInt8) {
enqueue([Frame.requestToken(token).encoded])
}

func select(_ preset: EQPreset) {
Expand Down Expand Up @@ -251,6 +360,9 @@ final class SpeakerManager: NSObject {
/// Forget what the last speaker reported, so none of it shows for whichever speaker connects next.
private func clearDeviceInfo() {
name = nil; colorCode = nil; battery = nil; isCharging = false; firmware = nil; eq = nil
infoTokens = [:]
linkMode = nil; playTogether = nil; channel = nil; role = nil; stereoLock = nil
auracastSupportedToken = nil; linkedDevices = nil; auracastGroup = nil; pendingChannel = nil
}

private func clearDeviceState() {
Expand Down Expand Up @@ -320,6 +432,7 @@ final class SpeakerManager: NSObject {
// MARK: Incoming

private func handle(_ message: Incoming) {
if case .p4(let p4) = message { handleP4Party(p4) }
if let codec, let snapshot = codec.parse(message) {
let superseded = eqNext != nil
if eqInFlight { eqWriteFinished() }
Expand All @@ -334,14 +447,43 @@ final class SpeakerManager: NSObject {
switch Command(rawValue: frame.command) {
case .info:
guard let token = InfoToken.parse(frame.payload) else { return }
if frame.payload.count >= 3, frame.payload[1] != 0x48, frame.payload[1] != 0xC2 {
infoTokens[frame.payload[1]] = Array(frame.payload.dropFirst(2))
}
switch token {
case .name(let n): name = n
case .productID(let pid): setProductID(pid)
case .color(let c): colorCode = c
case .battery(let level, let charging): batteryChanged(level, charging: charging)
case .firmware(let f): firmware = f
case .auracast(let value): playTogether = value != 0
case .audioChannel(let c):
// Outside a group the firmware reports 00 even after an ACKed write.
if c != .mono || pendingChannel == nil || pendingChannel == .mono {
channel = c
if c != .mono { pendingChannel = nil }
}
case .stereoLock(let locked): stereoLock = locked
case .auracastSupport(let supported): auracastSupportedToken = supported
case .linkedDevices(let count): linkedDevices = count
default: break
}
case .linkMode:
// AA 6B 01 <role>: the answer to our 6A write.
if let value = frame.payload.first { role = DeviceRole(roleValue: value) }
case .linkRole:
if let value = frame.payload.first { role = DeviceRole(roleValue: value) }
case .auracastGroup:
guard !frame.payload.isEmpty else {
// An empty AA A2 means this unit is not in a group.
auracastGroup = nil
break
}
let group = AuracastGroup(payload: frame.payload)
auracastGroup = group
if let c = group.channel { channel = c; pendingChannel = c }
if let r = group.role { role = r }
if group.action == .destroy { auracastGroup = nil; channel = .mono; pendingChannel = .mono }
case .version:
firmware = FirmwareVersion.format(frame.payload)
case .notifyEQChange:
Expand All @@ -354,6 +496,23 @@ final class SpeakerManager: NSObject {
}
}

/// Protocol 4 carries Auracast and the stereo half as features, not AA frames.
private func handleP4Party(_ message: P4Message) {
if let value = message.features[P4Party.auracastMode]?.first {
linkMode = value == 0 ? .off : .auracast
}
if let value = message.features[P4Party.channel]?.first, let channel = AudioChannel(channel: value) {
self.channel = channel
}
guard message.features[P4Party.status] != nil || message.features[P4Party.groupType] != nil else { return }
var group = auracastGroup ?? AuracastGroup()
if let value = message.features[P4Party.groupType]?.first { group.type = AuracastGroupType(rawValue: value) }
if let value = message.features[P4Party.role]?.first { group.role = DeviceRole(roleValue: value) }
if let value = message.features[P4Party.channel]?.first { group.channel = AudioChannel(channel: value) }
if let id = message.features[P4Party.groupID] { group.groupID = id }
auracastGroup = group
}

/// Whether a sighting is the speaker we're already connected to, under another address.
private func isActiveSpeaker(_ s: DiscoveredSpeaker) -> Bool {
guard activeID != nil else { return false }
Expand Down Expand Up @@ -403,7 +562,7 @@ final class SpeakerManager: NSObject {
enqueue([
Frame.requestInfo.encoded, Frame.requestVersion.encoded, Frame(0x61).encoded,
Frame(0x6C, [0x00]).encoded, Frame.requestEQ.encoded,
] + P4Message.set([(P4EQ.query, [0xFF])]).packets)
] + auracastRequests + P4Message.set([(P4EQ.query, [0xFF])]).packets)
try? await Task.sleep(for: .seconds(3))
}

Expand Down Expand Up @@ -541,7 +700,7 @@ extension SpeakerManager: @preconcurrency CBPeripheralDelegate {
log.info("control channel ready")
decoder = MessageDecoder()
status = .connected
enqueue([Frame.requestInfo.encoded, Frame.requestVersion.encoded] + (codec?.readRequests() ?? []))
enqueue([Frame.requestInfo.encoded, Frame.requestVersion.encoded] + tokenRequests + auracastRequests + (codec?.readRequests() ?? []))
startPolling()
}

Expand Down
Loading