Bluetooth: TWS¶
JP150PCB 1.3PCB 1.4generatedJan PřibyslavskýThis page does not apply to the product or PCB revision chosen in the header.
True Wireless Stereo: the capability, pairing, the remembered peer, the roles, one answer for
polling, and diagnostics. The owner's view is in the Bluetooth section.
Three different things carry the word role: BT:TWS:FALLBACKROLE is the stored intent for a
start without a remembered peer, BT:TWS:ROLE? is what the live link negotiated, and
BT:TWS:BOOTOUTCOME? says what the last start did with the remembered peer. Many answers are
mirrors of the module's state that the firmware refreshes about every second or two, so a
change shows with that delay.
Commands¶
| Command | Function | Parameter | Answer | Since | Boards |
|---|---|---|---|---|---|
BT:TWS:ENABLED? |
TWS capability of the module | – | BT:TWS:ENABLED:<0|1> |
26.6.2 | 1.3, 1.4 |
BT:TWS:ENABLED |
Switch the TWS capability on or off | 0, 1 |
no answer | 26.6.2 | 1.3, 1.4 |
BT:TWS:FALLBACKROLE? |
Stored role for a start without a remembered peer | – | BT:TWS:FALLBACKROLE:<Standalone|Primary|Secondary> |
26.10.1 | 1.3, 1.4 |
BT:TWS:FALLBACKROLE |
Set the stored fallback role | 0, 1, 2 |
no answer | 26.10.1 | 1.3, 1.4 |
BT:TWS:STATE? |
Peer-link state | – | BT:TWS:STATE:<state> |
26.6.2 | 1.3, 1.4 |
BT:TWS:ROLE? |
Role negotiated by the live link | – | BT:TWS:ROLE:<Primary|Secondary|Unknown> |
26.10.1 | 1.3, 1.4 |
BT:TWS:PEER? |
Address of the remembered peer | – | BT:TWS:PEER:<12 hex digits> |
26.6.2 | 1.3, 1.4 |
BT:TWS:BOOTOUTCOME? |
What the last start did with the remembered peer | – | BT:TWS:BOOTOUTCOME:<outcome> |
26.10.1 | 1.3, 1.4 |
BT:TWS:STAT? |
The whole TWS state in one numeric answer, for polling | – | BT:TWS:STAT:<enabled>,<state>,<role>,<mac>,<fallbackrole>,<inq>,<pair>,<kept>,<seen> |
26.10.1 | 1.3, 1.4 |
BT:TWS:PAIR:START |
Start pairing as Primary without blocking the control interface | – | BT:TWS:PAIR:START:<OK|ERR:PAIRED|ERR:MODULE> |
26.10.1 | 1.3, 1.4 |
BT:TWS:PAIR:STATUS? |
Progress of that pairing | – | BT:TWS:PAIR:STATUS:<state> |
26.10.1 | 1.3, 1.4 |
BT:TWS:PAIR |
Pair as Primary, blocking for up to 15 s | – | BT:TWS:PAIR:<OK|AlreadyPaired|NoPeerFound|Error> |
26.6.2 | 1.3, 1.4 |
BT:TWS:REPAIR |
Forget the peer and pair again in the given role (Start New Pairing) | 0, 1, 2 |
BT:TWS:REPAIR:<OK|ERR:PARAM|ERR:NVM|ERR:BUSY> |
26.10.1 | 1.3, 1.4 |
BT:TWS:REBOOT |
Apply a role now; restarts the Bluetooth module | 0, 1, 2 |
BT:TWS:REBOOT:<OK|ERR:PARAM|ERR:BUSY> |
26.10.1 | 1.3, 1.4 |
BT:TWS:CONN |
Reconnect the remembered peer | – | BT:TWS:CONN:<OK|ERR:DISABLED|ERR:PAIRED|ERR:NOPEER|ERR:MODULE> |
26.10.1 | 1.3, 1.4 |
BT:TWS:DISC |
Disconnect the peer and keep the pairing | – | BT:TWS:DISC:<OK|ERR:MODULE> |
26.10.1 | 1.3, 1.4 |
BT:TWS:BOND:DEL |
Forget the peer without disconnecting | – | BT:TWS:BOND:DEL:<OK|ERR:MODULE> |
26.10.1 | 1.3, 1.4 |
BT:TWS:UNPAIR |
Disconnect and forget the peer | – | BT:TWS:UNPAIR:<OK|ERR:MODULE> |
26.6.2 | 1.3, 1.4 |
BT:TWS:INQ? |
Whether a peer search runs | – | BT:TWS:INQ:<0|1> |
26.10.1 | 1.3, 1.4 |
BT:TWS:INQ |
Start or stop the peer search | 0, 1 |
BT:TWS:INQ:<OK|ERR:PARAM|ERR:MODULE> |
26.10.1 | 1.3, 1.4 |
BT:TWS:REFRESH |
Re-read the TWS state from the module | – | BT:TWS:REFRESH:<OK|ERR:MODULE> |
26.10.1 | 1.3, 1.4 |
BT:TWS:PEERLIST? |
The module's remembered devices, phones and the TWS peer | – | BT:TWS:PEERLIST:<count>[;<index>,<mac>,<istws>,<name>...] |
26.10.1 | 1.3, 1.4 |
BT:TWS:SCAN? |
Peers found by the last search | – | BT:TWS:SCAN:<count>[;<mac>,<rssi>,<type>,<name>...] |
26.6.2 | 1.3, 1.4 |
BT:TWS:SCAN:COUNT? |
Entries kept and seen in the last search | – | BT:TWS:SCAN:COUNT:<kept>,<seen> |
26.10.1 | 1.3, 1.4 |
BT:TWS:SCAN:ITEM? |
One entry of the last search | <index> |
BT:TWS:SCAN:ITEM:<mac>,<rssi>,<type>,<name>,<f1>,<f2> |
26.10.1 | 1.3, 1.4 |
BT:TWS:SCAN:DIAG? |
Diagnostics of the search-result parser | – | BT:TWS:SCAN:DIAG:<lines>,<parsed>,<kept>,<rc>,<legacyrc>,<rawlen>,<rawhex> |
26.10.1 | 1.3, 1.4 |
BT:TWS:PEERDIAG? |
Diagnostics of the peer-record parser | – | BT:TWS:PEERDIAG:<lines>,<rc>,<rawlen>,<rawhex> |
26.10.1 | 1.3, 1.4 |
Since is the release the command appeared in; 26.6.2 is the oldest release documented here, so a command marked 26.6.2 may be older.
BT:TWS:ENABLED¶
Commands: BT:TWS:ENABLED?, BT:TWS:ENABLED
The module stores the capability itself, so it survives power cycles. Switching it off tears
down a peer link; the peer-link state then reads Standby and the remembered peer is kept. A
value above 1 is an SCPI error. The pairing commands switch the capability on when needed.
BT:TWS:FALLBACKROLE¶
Commands: BT:TWS:FALLBACKROLE?, BT:TWS:FALLBACKROLE
Consulted at start only when no peer is remembered; a remembered peer is reconnected instead.
Changing it does not change the current session: BT:TWS:REBOOT applies a role now, and
BT:TWS:REPAIR sets and applies one in one step. An out-of-range value is an SCPI error. A
stored setting (autosave after 1 s). Replaces BT:BOOTROLE, whose query answered Master and
Slave.
Default: 1.
Fallback roles
| Value | Meaning |
|---|---|
0 |
Standalone, no TWS; the module behaves as a single Bluetooth speaker |
1 |
Primary; searches for a peer when none is remembered at start |
2 |
Secondary; waits to be found by a Primary |
BT:TWS:STATE?¶
A mirror refreshed about every 2 s while the capability is on.
Peer-link states
| Value | Meaning |
|---|---|
Unsupported |
The module does not report a peer link |
Standby |
No peer link; also the reading while the TWS capability is off |
Connecting |
A peer link is being set up |
Connected |
The peer link is up |
Streaming |
Audio flows over the peer link |
BT:TWS:ROLE?¶
Unknown until the module has reported its peer record once, and after the pairing was
deleted. Distinct from BT:TWS:FALLBACKROLE?, the stored intent for the next start.
Live roles
| Value | Meaning |
|---|---|
Primary |
This unit drives the pair |
Secondary |
This unit follows the pair |
Unknown |
No peer record has been read yet, or the pairing was deleted |
BT:TWS:PEER?¶
000000000000 when no peer is remembered.
BT:TWS:BOOTOUTCOME?¶
Settles once shortly after start, so it belongs on a slow poll. PeerUnreachable is the one
worth showing: a peer is remembered but did not answer, so the unit plays alone and keeps
doing so until the peer returns or the pair is made again (BT:TWS:REPAIR); without this
answer that state looks like never paired.
Start outcomes
| Value | Meaning |
|---|---|
Pending |
The start-up resolution has not finished yet |
NoPeer |
No peer was remembered; the fallback role applied |
Reconnected |
The remembered peer answered and the pair is up |
PeerUnreachable |
A peer is remembered but did not answer; the unit plays alone until the peer returns or it is paired again |
BT:TWS:STAT?¶
All fields numeric: enabled 0/1; state 0 Unsupported, 1 Standby, 2 Connecting,
3 Connected, 4 Streaming; role 0 Secondary, 1 Primary, 2 Unknown; mac the remembered peer
or -; fallbackrole 0 to 2; inq 0/1 whether a search runs; pair 0 Idle, 1 Inquiring,
2 OK, 3 NoPeerFound, 4 Error; kept and seen as BT:TWS:SCAN:COUNT?. A read of the
firmware's mirror, no traffic to the module: the one query to poll instead of five.
BT:TWS:PAIR:START, BT:TWS:PAIR:STATUS?¶
Commands: BT:TWS:PAIR:START, BT:TWS:PAIR:STATUS?
BT:TWS:PAIR:START drops a phone link, switches the capability on, starts the peer search and
returns once the search runs (it holds the control interface for about 0.7 s). ERR:PAIRED:
a peer link is already up; ERR:MODULE: the module refused a command, or an attempt is
already running. BT:TWS:PAIR:STATUS? advances once a second, so the result shows up to a
second after the link forms; a final value stays until the next start of a pairing, and
BT:TWS:REBOOT resets it to Idle. BT:TWS:INQ 0 aborts a running attempt. This pair of
commands replaces BT:TWS:PAIR in host software.
Pairing states
| Value | Meaning |
|---|---|
Idle |
No attempt since start, or reset by BT:TWS:REBOOT |
Inquiring |
The search runs |
OK |
The peer link reached Connected or Streaming |
NoPeerFound |
15 s passed without a peer; the search was stopped |
Error |
The module refused a command of the start sequence |
BT:TWS:PAIR:START -> BT:TWS:PAIR:START:OK
BT:TWS:PAIR:STATUS? -> BT:TWS:PAIR:STATUS:Inquiring
BT:TWS:PAIR:STATUS? -> BT:TWS:PAIR:STATUS:OK
BT:TWS:PAIR¶
The same sequence as BT:TWS:PAIR:START, but the answer waits for the result: the control
interface is blocked for up to 15 s, on both the USB and the UART link. Kept for compatibility;
use BT:TWS:PAIR:START.
Pairing results
| Value | Meaning |
|---|---|
OK |
The peer link came up within 15 s |
AlreadyPaired |
The peer link was already up; nothing was done |
NoPeerFound |
15 s passed without a peer; the search was stopped |
Error |
The module refused a command of the sequence |
BT:TWS:REPAIR¶
The software equivalent of the long button press of a commercial TWS speaker, and the command
for a remembered peer that has become unreachable. In one action: the new fallback role is
stored (ERR:NVM when that write fails, and nothing else is done), the phone links are
dropped, the peer memory is wiped, the Bluetooth module is reset with the proper timing, and
the role is applied, all without a restart of the amplifier. OK means queued: the sequence
runs from the Bluetooth task in the next 4 to 6 s, during which the BT:* mirrors are stale.
ERR:BUSY when a request is already pending. MuraLink's Start New Pairing uses it.
BT:TWS:REBOOT¶
Applies a role immediately instead of at the next start: wipes the pairing, resets and
re-powers the module and configures TWS for the role. OK means queued; the sequence takes
4 to 6 s, during which the BT:* mirrors are stale. Does not change BT:TWS:FALLBACKROLE:
set both when the role should survive a power cycle, or use BT:TWS:REPAIR. ERR:BUSY when
a request is already pending.
BT:TWS:CONN, BT:TWS:DISC¶
Commands: BT:TWS:CONN, BT:TWS:DISC
BT:TWS:DISC drops the peer link and keeps the pairing, so the pair can come back without
pairing again; the module does not reconnect on its own, BT:TWS:CONN does it. The firmware
checks before it asks the module, because the module accepts a connect request even without a
pairing and then does nothing: ERR:DISABLED with the capability off, ERR:PAIRED with the
link already up, ERR:NOPEER without a remembered peer. OK means the request went to the
module; the link comes up a few seconds later and shows in BT:TWS:STAT?.
BT:TWS:BOND:DEL, BT:TWS:UNPAIR¶
Commands: BT:TWS:BOND:DEL, BT:TWS:UNPAIR
BT:TWS:UNPAIR is BT:TWS:DISC followed by BT:TWS:BOND:DEL. After either, BT:TWS:ROLE?
reads Unknown and BT:TWS:STAT? reports - for the peer. The capability stays on so that a
later pairing does not need to switch it on. OK confirms that the module accepted the
commands, not that the peer noticed.
BT:TWS:INQ¶
Commands: BT:TWS:INQ?, BT:TWS:INQ
1 starts a search that connects to the first peer found and clears the scan list; 0 stops
it, which also aborts a running BT:TWS:PAIR:START. The query is best effort: it tracks the
searches the firmware started, and clears when the peer link comes up. A search the module
starts on its own is not seen.
BT:TWS:REFRESH¶
Asks the module for its capability, link state and peer record at once instead of waiting for
the next polling cycle. OK confirms the questions were sent; the answers land within about
1 s and show in BT:TWS:STAT?.
BT:TWS:PEERLIST?¶
The module keeps phone pairings and the TWS peer in one list; istws is 1 for the entry
that is the current TWS peer. An empty memory answers 0, so that nothing remembered is
stated rather than inferred. The firmware asks the module and waits briefly for the list, so
the answer takes a moment. BT:TWS:PEERLIST:ERR:MODULE when the module could not be asked.
BT:TWS:PEERLIST? -> BT:TWS:PEERLIST:2;0,4142DE0BCDAC,1,JP150;1,A1B2C3D4E5F6,0,Jan's phone
BT:TWS:PEERLIST? -> BT:TWS:PEERLIST:0
BT:TWS:SCAN?, BT:TWS:SCAN:COUNT?, BT:TWS:SCAN:ITEM?¶
Commands: BT:TWS:SCAN?, BT:TWS:SCAN:COUNT?, BT:TWS:SCAN:ITEM?
The list is cleared when a search starts and holds up to 8 entries; seen counts every
well-formed hit of the search (up to 255), so seen above kept means peers were found and
dropped for lack of space. BT:TWS:SCAN? returns the whole list in one line and stops
appending when the line would overflow, so COUNT? plus ITEM? is the complete form.
ITEM? answers :ERR:RANGE for an index at or past kept and :ERR:PARAM for a bad
parameter; f1 and f2 are two fields of the module's report whose meaning the vendor does
not document.
BT:TWS:SCAN? -> BT:TWS:SCAN:2;4142DE0BCDAC,-78,10,Secondary-AMP;AABBCCDDEEFF,-92,2,
BT:TWS:SCAN:COUNT? -> BT:TWS:SCAN:COUNT:2,2
BT:TWS:SCAN:ITEM? 0 -> BT:TWS:SCAN:ITEM:4142DE0BCDAC,-78,10,Secondary-AMP,1,2
BT:TWS:SCAN:DIAG?, BT:TWS:PEERDIAG?¶
Commands: BT:TWS:SCAN:DIAG?, BT:TWS:PEERDIAG?
Two parser diagnostics for support cases: how many report lines of the module arrived, how
many were decoded, and the last line as raw hex (at most 64 bytes), because the module's lines
can contain bytes that would corrupt a plain answer. Used when a search finds nothing
(BT:TWS:SCAN:ITEM? 0 answers ERR:RANGE) or when a streaming pair reports its role as
Unknown. The counters reset when a search starts and when the module stops answering.
Changes¶
- 26.10.1: added
BT:TWS:ROLE?,BT:TWS:STAT?,BT:TWS:PAIR:START,BT:TWS:PAIR:STATUS?,BT:TWS:INQ?,BT:TWS:INQ,BT:TWS:DISC,BT:TWS:CONN,BT:TWS:BOND:DEL,BT:TWS:REBOOT,BT:TWS:SCAN:COUNT?,BT:TWS:SCAN:ITEM?,BT:TWS:SCAN:DIAG?,BT:TWS:PEERDIAG?,BT:TWS:BOOTOUTCOME?,BT:TWS:PEERLIST?,BT:TWS:REPAIR,BT:TWS:REFRESH,BT:TWS:FALLBACKROLE?,BT:TWS:FALLBACKROLE; removedBT:BOOTROLE?,BT:BOOTROLE. - 26.6.2 (oldest release documented): 9 commands.