WHAD Discovery service

The discovery service is a key element of WHAD, as it provides a series of messages that are used to discover a device information, supported domains and capabilities.

All the following messages are defined in the device.proto file.

Discovery procedures

Device initialization

sequenceDiagram participant Host participant Interface Host->>+Interface: DeviceResetQuery Interface->>-Host:DeviceReadyResp

When WHAD initializes a device, it sends a DeviceResetQuery message to this device and expects to receive a DeviceReadyResp once the device has successfully restarted and is ready to use.

Supporting this message is mandatory as it is litterally the first message WHAD will send to a device. Most of our compatible devices just reset their internal state and answer back with a DeviceReadyResp message.

Once the device reset, the host sends a DeviceInfoQuery message to get some information on this device and to determine:

• the version of WHAD protocol it supports in order to avoid sending messages this device will not understand

• the supported domains and the related capabilities for each of them

The device must answer with a DeviceInfoResp message including all the required information. If it does not, the host will consider the device unresponding and will stop the communication.

Device domains discovery

sequenceDiagram participant Host participant Interface Host->>+Interface: DeviceInfoQuery Interface->>-Host: DeviceInfoResp

Once the device reset, the host sends a DeviceInfoQuery message to get some information on this device and to determine:

• the version of WHAD protocol it supports in order to avoid sending messages this device will not understand

• the supported domains and the related capabilities for each of them

The device must answer with a DeviceInfoResp message including all the required information. If it does not, the host will consider the device unresponding and will stop the communication.

Per-domain capabilities discovery

sequenceDiagram participant Host participant Interface Host->>+Interface: DeviceDomainInfoQuery(domain=Domain.BtLE) Interface->>-Host: DeviceDomainInfoResp Host->>+Interface: DeviceDomainInfoQuery(domain=Domain.Phy) Interface->>-Host: DeviceDomainInfoResp

Once the domains have been successfully discovered, the host will send for each of them a DeviceDomainInfoQuery message and expect the device to answer each one with a corresponding DeviceDomainInfoResp message.

Device transport speed modification

sequenceDiagram participant Host participant Interface Host->>+Interface: SetTransportSpeed(1000000) Interface->>Host: CommandResult(result=SUCCESS) Host->>Host: Update transport speed Interface->>-Host: DeviceReadyResp

This discovery phase is always performed with the transport default speed. For UART, it is set to 115200 bauds by default. Some devices however support higher speeds and keeping using a low speed while communication may be faster is not a good idea.

The host can ask the WHAD device to update its communication speed by sending a SetTransportSpeed message. Once this message issued, the target device is expected to update its speed while the host also reconfigure its interface, and the host expects to receive a DeviceReadyResp message from the device.

If no message is received by the host after its interface reconfiguration, the device is considered as disconnected and the host will drop the communication.

Enumerations

Domain

This enumeration lists all the supported domains, including some that are not yet defined in our WHAD protocol.

DeviceType

This enumeration lists some of the currently supported devices. You can ask us to add yours in this list.

Capability

This enumeration lists all the capability flags that can be combined in a DeviceInfoResp message.

Value	Description
_CapNone	No specific capability
Scan	Device can scan and detect other devices
Sniff	Device is able to sniff data
Inject	Device can inject/send data
Jam	Device can jam
Hijack	Device is able to hijack connections
SimulateRole	Device can act as a specific role
NoRawData	Device cannot send or receive raw data

Messages

DeviceResetQuery

This message asks the device to reset its internal state to default. If the device was performing some action, this action is stopped and it switches to idle mode.

Note

This message has no field.

DeviceReadyResp

This message is sent by a WHAD device to its host, notifying the device is ready to operate and in idle mode.

Note

This message has no fields

DeviceInfoQuery

This message is sent by the host to a compatible device to ask for its information.

Field	Type	Description
proto_ver	uint32	Version of WHAD protocol supported by the host

DeviceInfoResp

This message is sent by the host to the device to retrieve some information about the device:

Field	Type	Description
type	uint32	Device type, represented by a standard code
devid	bytes	Device unique ID (can be readable)
proto_min_ver	uint32	Minimal WHAD protocol supported version
max_speed	uint32	Maximum supported speed for transport
fw_author	bytes	Firmware author name
fw_url	bytes	Firmware source code URL (github repo, …)
fw_version_major	uint32	Firmware version major number
fw_version_minor	uint32	Firmware version minor number
fw_version_rev	uint32	Firmware version rev number
capabilities	uint32[]	List of capabilities

Device capabilities are provided as a list of uint32 values, with each value composed of a domain (from Domain) or’ed with a set of Capability. The host can therefore enumerates the supported domains and for each of them retrieve the supported capabilities.

In WHAD, a capability determine what a device can do related to a specific protocol:

• _CapNone: indicates the device has no capability at all

• Scan: can scan on the target protocol and discover devices

• Sniff: can sniff packets or data and report it to the host

• Inject: can inject packets or data (not related to a connection)

• Jam: can jam the target protocol, usually a single channel

• Hijack: can take over an existing connection

• Hook: can perform a Man-in-the-Middle attack

• SimulateRole: can mimick a protocol-specific role

• NoRawData: cannot report raw data (use this when a WHAD device cannot get all the low-level layer for a specific protocol)

DeviceDomainInfoQuery

This message is sent by the host to ask a compatible device to give a detailed overview of the commands it supports for a given domain.

Field	Type	Description
domain	uint32	Target domain as defined in Domain

DeviceDomainInfoResp

This message is sent by the device to the host and specifies the supported commands for the requested domain.

Field	Type	Description
domain	uint32	Target domain as defined in Domain
supported_commands	uint64	Bitmap of supported commands

The supported_commands bitmap has a bit set for each command ID it supports, meaning each domain can have a maximum number of 64 commands.

SetTransportSpeed

This message asks the device to change its communication speed. If the device uses UART communication, then it must update its baudrate to the one provided by the host, and then issue a DeviceReadyResp to tell the host that it is ready to proceed.

Field	Type	Description
speed	uint32	Requested speed

Attention

Requested speed must not exceed the device’s maximal speed as stated in its DeviceInfoResp message.