The Ledger Nano X acts as a GATT server.
The link shall preferably be established using a LE Secure Connection supporting Numeric Comparison. LE legacy pairing is optionally available with a warning displayed to the user.
The service UUID is 13D63400-2C97-0004-0000-4C6564676572 and it implements the following characteristics :
Name |
Property |
Length |
UUID |
Request |
Write |
20 to 153 bytes |
13D63400-2C97-0004-0002-4C6564676572 |
Response |
Notify |
20 to 153 bytes |
13D63400-2C97-0004-0001-4C6564676572 |
The value of the negociated MTU can be queried from the higher level transport protocol to optimize the size of fragments sent to the Ledger Nano X as described below.
A communication between a host and the Ledger Nano X is performed as follows :
-
The Ledger Nano X is turned on
-
The Ledger Nano X advertises its service
-
The Client scans for the Ledger Nano X service
-
The Client performs characteristic discovery on the Ledger Nano X
-
If not already paired, the Client and the Ledger Nano X shall perform BLE pairing and create a LTK. A confirmation will be prompted on the Ledger Nano X
-
The Client registers for notifications on the Response characteristic
-
The Client formats and writes a request into the Request characteristic. As a first request, the Client queries the negociated MTU or uses the minimum BLE payload length if not available
-
The Ledger Nano X processes the request and responds by sending notifications over the Response characteristic. The Ledger Nano X can indicate that the connection should be closed and reopened later if significant processing time is expected.
-
The connection is closed by the Client or the connection times out and is closed by the Ledger Nano X
Note : in order for the bonding information to be writtent in NVM, the client shall disconnect from the Nano X. If the disconnection is initiated from the Nano X bonding information won't be writtent in NVM.
Requests and responses are encapsulated using a flexible protocol allowing to fragment large payloads.
The initial packet in a sequence is formatted as follows :
Description |
Length |
Command tag |
1 |
Packet sequence index (big endian), set to 0 |
2 |
Data length (big endian) |
2 |
Payload |
var |
The following packets in a sequence are formatted as follows :
Description |
Length |
Command tag |
1 |
Packet sequence index (big endian) |
2 |
Payload |
var |
The Command tag describes the message content. A response is sent with a Command tag matching the request or set to 0x0E to report a protocol error.
The Packet sequence index describes the current sequence for fragmented payloads. The first fragment index is 0x00 and increased in following packets.
The APDU command tag 0x05 is used to transfer application specific data.
You can refer to the following documents to obtain additional details about the APDU format :
-
Bitcoin application documentation (https://raw.githubusercontent.com/LedgerHQ/ledger-app-btc/master/doc/btc.asc)
-
Ethereum application documentation (https://raw.githubusercontent.com/LedgerHQ/ledger-app-eth/master/doc/ethapp.asc)
-
LedgerJS applications (https://github.com/ledgerhq/ledgerjs#ledgerhqhw-app-)
The GET MTU command tag 0x08 is used to query the negociated MTU and optimize the size of fragments
The command packet shall be formatted as follows
Description |
Length |
Command tag 0x08 |
1 |
Packet sequence index (big endian), set to 0 |
2 |
Data length (big endian), set to 0 |
2 |
The command response is formatted as follows
Description |
Length |
Command tag 0x08 |
1 |
Packet sequence index (big endian), set to 0 |
2 |
Data length (big endian), set to 1 |
2 |
Negociated MTU size |
1 |
The GET VERSION command tag 0x00 is used to query the current version of the protocol being used
The command packet shall be formatted as follows
Description |
Length |
Command tag 0x00 |
1 |
Packet sequence index (big endian), set to 0 |
2 |
Data length (big endian), set to 0 |
2 |
The command response is formatted as follows
Description |
Length |
Command tag 0x00 |
1 |
Packet sequence index (big endian), set to 0 |
2 |
Data length (big endian), set to 4 |
2 |
Protocol version (big endian), currently 0 |
4 |
The INIT command tag 0x01 is used to reset the high level BLE state machine in case the host lost information about its current state
The command packet shall be formatted as follows
Description |
Length |
Command tag 0x01 |
1 |
Packet sequence index (big endian), set to 0 |
2 |
Data length (big endian), set to 0 |
2 |
The command response is formatted as follows
Description |
Length |
Command tag 0x01 |
1 |
Packet sequence index (big endian), set to 0 |
2 |
Data length (big endian), set to 0 |
2 |