stm32wb_hci::vendor::command::gap

Trait GapCommands

Source 
pub trait GapCommands {

Show 54 methods    // Required methods
    async fn gap_set_nondiscoverable(&mut self);
    async fn set_limited_discoverable(
        &mut self,
        params: &DiscoverableParameters<'_, '_>,
    ) -> Result<(), Error>;
    async fn set_discoverable(
        &mut self,
        params: &DiscoverableParameters<'_, '_>,
    ) -> Result<(), Error>;
    async fn set_direct_connectable(
        &mut self,
        params: &DirectConnectableParameters,
    ) -> Result<(), Error>;
    async fn set_io_capability(&mut self, capability: IoCapability);
    async fn set_authentication_requirement(
        &mut self,
        requirements: &AuthenticationRequirements,
    ) -> Result<(), Error>;
    async fn set_authorization_requirement(
        &mut self,
        conn_handle: ConnectionHandle,
        authorization_required: bool,
    );
    async fn pass_key_response(
        &mut self,
        conn_handle: ConnectionHandle,
        pin: u32,
    ) -> Result<(), Error>;
    async fn authorization_response(
        &mut self,
        conn_handle: ConnectionHandle,
        authorization: Authorization,
    );
    async fn init(
        &mut self,
        role: Role,
        privacy_enabled: bool,
        dev_name_characteristic_len: u8,
    );
    async fn set_nonconnectable(
        &mut self,
        advertising_type: AdvertisingType,
        address_type: AddressType,
    ) -> Result<(), Error>;
    async fn set_undirected_connectable(
        &mut self,
        params: &UndirectedConnectableParameters,
    ) -> Result<(), Error>;
    async fn peripheral_security_request(
        &mut self,
        conn_handle: &ConnectionHandle,
    );
    async fn update_advertising_data(
        &mut self,
        data: &[u8],
    ) -> Result<(), Error>;
    async fn delete_ad_type(&mut self, ad_type: AdvertisingDataType);
    async fn get_security_level(&mut self, conn_handle: &ConnectionHandle);
    async fn set_event_mask(&mut self, flags: EventFlags);
    async fn configure_white_list(&mut self);
    async fn terminate(
        &mut self,
        conn_handle: ConnectionHandle,
        reason: Status,
    ) -> Result<(), Error>;
    async fn clear_security_database(&mut self);
    async fn allow_rebond(&mut self, conn_handle: ConnectionHandle);
    async fn start_limited_discovery_procedure(
        &mut self,
        params: &DiscoveryProcedureParameters,
    );
    async fn start_general_discovery_procedure(
        &mut self,
        params: &DiscoveryProcedureParameters,
    );
    async fn start_auto_connection_establishment_procedure(
        &mut self,
        params: &AutoConnectionEstablishmentParameters<'_>,
    ) -> Result<(), Error>;
    async fn start_general_connection_establishment_procedure(
        &mut self,
        params: &GeneralConnectionEstablishmentParameters,
    );
    async fn start_selective_connection_establishment_procedure(
        &mut self,
        params: &SelectiveConnectionEstablishmentParameters<'_>,
    ) -> Result<(), Error>;
    async fn create_connection(&mut self, params: &ConnectionParameters);
    async fn terminate_gap_procedure(
        &mut self,
        procedure: Procedure,
    ) -> Result<(), Error>;
    async fn start_connection_update(
        &mut self,
        params: &ConnectionUpdateParameters,
    );
    async fn send_pairing_request(&mut self, params: &PairingRequest);
    async fn resolve_private_address(&mut self, addr: BdAddr);
    async fn set_broadcast_mode(
        &mut self,
        params: &BroadcastModeParameters<'_, '_>,
    ) -> Result<(), Error>;
    async fn start_observation_procedure(
        &mut self,
        params: &ObservationProcedureParameters,
    );
    async fn get_bonded_devices(&mut self);
    async fn is_device_bonded(&mut self, addr: PeerAddrType);
    async fn numeric_comparison_value_confirm_yes_no(
        &mut self,
        params: &NumericComparisonValueConfirmYesNoParameters,
    );
    async fn passkey_input(
        &mut self,
        conn_handle: ConnectionHandle,
        input_type: InputType,
    );
    async fn get_oob_data(&mut self, oob_data_type: OobDataType);
    async fn set_oob_data(&mut self, params: &SetOobDataParameters);
    async fn add_devices_to_resolving_list(
        &mut self,
        whitelist_identities: &[PeerAddrType],
        clear_resolving_list: bool,
    );
    async fn remove_bonded_device(&mut self, address: BdAddrType);
    async fn add_devices_to_list(
        &mut self,
        list_entries: &[BdAddrType],
        mode: AddDeviceToListMode,
    );
    async fn additional_beacon_start(
        &mut self,
        params: &AdditonalBeaconStartParameters,
    ) -> Result<(), Error>;
    async fn additional_beacon_stop(&mut self);
    async fn additonal_beacon_set_data(&mut self, advertising_data: &[u8]);
    async fn adv_set_config(&mut self, params: &AdvSetConfig);
    async fn adv_set_enable<'a>(&mut self, params: &AdvSetEnable<'a>);
    async fn adv_set_advertising_data(
        &mut self,
        params: &AdvSetAdvertisingData<'_>,
    );
    async fn adv_set_scan_response_data(
        &mut self,
        params: &AdvSetAdvertisingData<'_>,
    );
    async fn adv_remove_set(&mut self, handle: AdvertisingHandle);
    async fn adv_clear_sets(&mut self);
    async fn adv_set_random_address(
        &mut self,
        handle: AdvertisingHandle,
        addr: BdAddr,
    );

    // Provided methods
    async fn init_gap(
        &mut self,
        role: Role,
        privacy_enabled: bool,
        dev_name_characteristic_len: u8,
    ) { ... }
    async fn set_gap_event_mask(&mut self, flags: EventFlags) { ... }

}
Expand description

GAP-specific commands.

Required Methods§

Source

async fn gap_set_nondiscoverable(&mut self)

Set the device in non-discoverable mode. This command will disable the LL advertising and put the device in standby state.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn set_limited_discoverable( &mut self, params: &DiscoverableParameters<'_, '_>, ) -> Result<(), Error>

Set the device in limited discoverable mode.

Limited discoverability is defined in in GAP specification volume 3, section 9.2.3. The device will be discoverable for maximum period of TGAP (lim_adv_timeout) = 180 seconds (from errata). The advertising can be disabled at any time by issuing a set_nondiscoverable command.

§Errors
§Generated evenst

When the controller receives the command, it will generate a command status event. The controller starts the advertising after this and when advertising timeout happens (i.e. limited discovery period has elapsed), the controller generates an GAP Limited Discoverable Complete event.

Source

async fn set_discoverable( &mut self, params: &DiscoverableParameters<'_, '_>, ) -> Result<(), Error>

Set the device in discoverable mode.

Limited discoverability is defined in in GAP specification volume 3, section 9.2.4. The device will be discoverable for maximum period of TGAP (lim_adv_timeout) = 180 seconds (from errata). The advertising can be disabled at any time by issuing a set_nondiscoverable command.

§Errors
§Generated evenst

A Command Complete event is generated.

Source

async fn set_direct_connectable( &mut self, params: &DirectConnectableParameters, ) -> Result<(), Error>

Set the device in direct connectable mode.

Direct connectable mode is defined in GAP specification Volume 3, Section 9.3.3). Device uses direct connectable mode to advertise using either High Duty cycle advertisement events or Low Duty cycle advertisement events and the address as what is specified in the Own Address Type parameter. The Advertising Type parameter in the command specifies the type of the advertising used.

When the ms feature is not enabled, the device will be in directed connectable mode only for 1.28 seconds. If no connection is established within this duration, the device enters non discoverable mode and advertising will have to be again enabled explicitly.

When the ms feature is enabled, the advertising interval is explicitly provided in the parameters.

§Errors
§Generated evenst

A Command Complete event is generated.

Source

async fn set_io_capability(&mut self, capability: IoCapability)

Set the IO capabilities of the device.

This command has to be given only when the device is not in a connected state.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn set_authentication_requirement( &mut self, requirements: &AuthenticationRequirements, ) -> Result<(), Error>

Set the authentication requirements for the device.

This command has to be given only when the device is not in a connected state.

§Errors
§Generated events
Source

async fn set_authorization_requirement( &mut self, conn_handle: ConnectionHandle, authorization_required: bool, )

Set the authorization requirements of the device.

This command has to be given when connected to a device if authorization is required to access services which require authorization.

§Errors

Only underlying communication errors are reported.

§Generated events
Source

async fn pass_key_response( &mut self, conn_handle: ConnectionHandle, pin: u32, ) -> Result<(), Error>

This command should be send by the host in response to the GAP Pass Key Request event.

pin contains the pass key which will be used during the pairing process.

§Errors
  • BadFixedPin if the pin is greater than 999999.
  • Underlying communication errors.
§Generated events
Source

async fn authorization_response( &mut self, conn_handle: ConnectionHandle, authorization: Authorization, )

This command should be send by the host in response to the GAP Authorization Request event.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn init( &mut self, role: Role, privacy_enabled: bool, dev_name_characteristic_len: u8, )

Register the GAP service with the GATT.

The device name characteristic and appearance characteristic are added by default and the handles of these characteristics are returned in the event data.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn set_nonconnectable( &mut self, advertising_type: AdvertisingType, address_type: AddressType, ) -> Result<(), Error>

Put the device into non-connectable mode.

This mode does not support connection. The privacy setting done in the init command plays a role in deciding the valid parameters for this command. If privacy was not enabled, address_type may be Public or Random. If privacy was enabled, address_type may be ResolvablePrivate or NonResolvablePrivate.

§Errors
§Generated events

A Command Complete event is generated.

Source

async fn set_undirected_connectable( &mut self, params: &UndirectedConnectableParameters, ) -> Result<(), Error>

Put the device into undirected connectable mode.

The privacy setting done in the init command plays a role in deciding the valid parameters for this command.

§Errors
§Generated events

A Command Complete event is generated.

Source

async fn peripheral_security_request(&mut self, conn_handle: &ConnectionHandle)

This command has to be issued to notify the central device of the security requirements of the peripheral.

§Errors

Only underlying communication errors are reported.

§Generated events

A command status event will be generated when a valid command is received. On completion of the command, i.e. when the security request is successfully transmitted to the master, a GAP Peripheral Security Initiated vendor-specific event will be generated.

Source

async fn update_advertising_data(&mut self, data: &[u8]) -> Result<(), Error>

This command can be used to update the advertising data for a particular AD type. If the AD type specified does not exist, then it is added to the advertising data. If the overall advertising data length is more than 31 octets after the update, then the command is rejected and the old data is retained.

§Errors
§Generated events

A Command Complete event is generated.

Source

async fn delete_ad_type(&mut self, ad_type: AdvertisingDataType)

This command can be used to delete the specified AD type from the advertisement data if present.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn get_security_level(&mut self, conn_handle: &ConnectionHandle)

This command can be used to get the current security settings of the device.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn set_event_mask(&mut self, flags: EventFlags)

Allows masking events from the GAP.

The default configuration is all the events masked.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn configure_white_list(&mut self)

Configure the controller’s white list with devices that are present in the security database.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn terminate( &mut self, conn_handle: ConnectionHandle, reason: Status, ) -> Result<(), Error>

Command the controller to terminate the connection.

§Errors
§Generated events

The controller will generate a command status event when the command is received and a Disconnection Complete event will be generated when the link is disconnected.

Source

async fn clear_security_database(&mut self)

Clear the bonding table. All the devices in the bonding table are removed.

See also remove_bonded_device to remove only one device.

§Note

As a fallback mode, in case the bonding table is full, the BLE stack automatically clears the bonding table just before putting into it information about a new bonded device.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated.

Source

async fn allow_rebond(&mut self, conn_handle: ConnectionHandle)

This command should be given by the application when it receives the GAP Bond Lost event if it wants the re-bonding to happen successfully. If this command is not given on receiving the event, the bonding procedure will timeout.

§Errors

Only underlying communication errors are reported.

§Generated events

A Command Complete event is generated. Even if the command is given when it is not valid, success will be returned but internally it will have no effect.

Source

async fn start_limited_discovery_procedure( &mut self, params: &DiscoveryProcedureParameters, )

Start the limited discovery procedure.

The controller is commanded to start active scanning. When this procedure is started, only the devices in limited discoverable mode are returned to the upper layers.

§Errors

Only underlying communication errors are reported.

§Generated events

A command status event is generated as soon as the command is given.

If Success is returned in the command status, the procedure is terminated when either the upper layers issue a command to terminate the procedure by issuing the command terminate_procedure with the procedure code set to LimitedDiscovery or a timeout happens. When the procedure is terminated due to any of the above reasons, a ProcedureComplete event is returned with the procedure code set to LimitedDiscovery.

The device found when the procedure is ongoing is returned to the upper layers through the LeAdvertisingReport event.

Source

async fn start_general_discovery_procedure( &mut self, params: &DiscoveryProcedureParameters, )

Start the general discovery procedure. The controller is commanded to start active scanning.

§Errors

Only underlying communication errors are reported.

§Generated events

A command status event is generated as soon as the command is given.

If Success is returned in the command status, the procedure is terminated when either the upper layers issue a command to terminate the procedure by issuing the command terminate_procedure with the procedure code set to GeneralDiscovery or a timeout happens. When the procedure is terminated due to any of the above reasons, a ProcedureComplete event is returned with the procedure code set to GeneralDiscovery.

The device found when the procedure is ongoing is returned to the upper layers through the LeAdvertisingReport event.

Source

async fn start_auto_connection_establishment_procedure( &mut self, params: &AutoConnectionEstablishmentParameters<'_>, ) -> Result<(), Error>

Start the auto connection establishment procedure.

The devices specified are added to the white list of the controller and a le_create_connection call will be made to the controller by GAP with the initiator filter policy set to WhiteList, to “use whitelist to determine which advertiser to connect to”. When a command is issued to terminate the procedure by upper layer, a le_create_connection_cancel call will be made to the controller by GAP.

§Errors
  • If the white_list is too long (such that the serialized command would not fit in 255 bytes), a WhiteListTooLong is returned. The list cannot have more than 33 elements.
Source

async fn start_general_connection_establishment_procedure( &mut self, params: &GeneralConnectionEstablishmentParameters, )

Start a general connection establishment procedure.

The host enables scanning in the controller with the scanner filter policy set to AcceptAll, to “accept all advertising packets” and from the scanning results, all the devices are sent to the upper layer using the event LE Advertising Report. The upper layer then has to select one of the devices to which it wants to connect by issuing the command create_connection. If privacy is enabled, then either a private resolvable address or a non-resolvable address, based on the address type specified in the command is set as the scanner address but the GAP create connection always uses a private resolvable address if the general connection establishment procedure is active.

§Errors

Only underlying communication errors are reported.

Source

async fn start_selective_connection_establishment_procedure( &mut self, params: &SelectiveConnectionEstablishmentParameters<'_>, ) -> Result<(), Error>

Start a selective connection establishment procedure.

The GAP adds the specified device addresses into white list and enables scanning in the controller with the scanner filter policy set to WhiteList, to “accept packets only from devices in whitelist”. All the devices found are sent to the upper layer by the event LE Advertising Report. The upper layer then has to select one of the devices to which it wants to connect by issuing the command create_connection.

§Errors
  • If the white_list is too long (such that the serialized command would not fit in 255 bytes), a WhiteListTooLong is returned. The list cannot have more than 35 elements.
Source

async fn create_connection(&mut self, params: &ConnectionParameters)

Start the direct connection establishment procedure.

A LE Create Connection call will be made to the controller by GAP with the initiator filter policy set to UseAddress to “ignore whitelist and process connectable advertising packets only for the specified device”. The procedure can be terminated explicitly by the upper layer by issuing the command terminate_procedure. When a command is issued to terminate the procedure by upper layer, a le_create_connection_cancel call will be made to the controller by GAP.

§Errors

Only underlying communication errors are reported.

§Generated events

A command status event is generated as soon as the command is given. If Success is returned, on termination of the procedure, a LE Connection Complete event is returned. The procedure can be explicitly terminated by the upper layer by issuing the command terminate_procedure with the procedure_code set to DirectConnectionEstablishment.

Source

async fn terminate_gap_procedure( &mut self, procedure: Procedure, ) -> Result<(), Error>

The GAP procedure(s) specified is terminated.

§Errors
  • NoProcedure if the bitfield is empty.
  • Underlying communication errors
§Generated events

A command complete event is generated for this command. If the command was successfully processed, the status field will be Success and a ProcedureCompleted event is returned with the procedure code set to the corresponding procedure.

Source

async fn start_connection_update(&mut self, params: &ConnectionUpdateParameters)

Start the connection update procedure.

A le_connection_update call is be made to the controller by GAP.

§Errors

Only underlying communication errors are reported.

§Generated events

A command status event is generated as soon as the command is given. If Success is returned, on completion of connection update, a LeConnectionUpdateComplete event is returned to the upper layer.

Source

async fn send_pairing_request(&mut self, params: &PairingRequest)

Send the SM pairing request to start a pairing process. The authentication requirements and I/O capabilities should be set before issuing this command using the set_io_capability and set_authentication_requirement commands.

§Errors

Only underlying communication errors are reported.

§Generated events

A command status event is generated when the command is received. If Success is returned in the command status event, a Pairing Complete event is returned after the pairing process is completed.

Source

async fn resolve_private_address(&mut self, addr: BdAddr)

This command tries to resolve the address provided with the IRKs present in its database.

If the address is resolved successfully with any one of the IRKs present in the database, it returns success and also the corresponding public/static random address stored with the IRK in the database.

§Errors

Only underlying communication errors are reported.

§Generated events

A command complete event is generated. If Success is returned as the status, then the address is also returned in the event.

Source

async fn set_broadcast_mode( &mut self, params: &BroadcastModeParameters<'_, '_>, ) -> Result<(), Error>

This command puts the device into broadcast mode.

§Errors
§Generated events

A command complete event is returned where the status indicates whether the command was successful.

Source

async fn start_observation_procedure( &mut self, params: &ObservationProcedureParameters, )

Starts an Observation procedure, when the device is in Observer Role.

The host enables scanning in the controller. The advertising reports are sent to the upper layer using standard LE Advertising Report Event. See Bluetooth Core v4.1, Vol. 2, part E, Ch. 7.7.65.2, LE Advertising Report Event.

§Errors

Only underlying communication errors are reported.

§Generated events

A command complete event is generated.

Source

async fn get_bonded_devices(&mut self)

This command gets the list of the devices which are bonded. It returns the number of addresses and the corresponding address types and values.

§Errors

Only underlying communication errors are reported.

§Generated events

A command complete event is generated.

Source

async fn is_device_bonded(&mut self, addr: PeerAddrType)

The command finds whether the device, whose address is specified in the command, is bonded. If the device is using a resolvable private address and it has been bonded, then the command will return Success.

§Errors

Only underlying communication errors are reported.

§Generated events

A command complete event is generated.

Source

async fn numeric_comparison_value_confirm_yes_no( &mut self, params: &NumericComparisonValueConfirmYesNoParameters, )

This command allows the user to validate/confirm or not the numeric comparison value showed through the [NumericComparisonValueEvent]

Source

async fn passkey_input( &mut self, conn_handle: ConnectionHandle, input_type: InputType, )

This command permits to signal to the Stack the input type detected during Passkey input.

Source

async fn get_oob_data(&mut self, oob_data_type: OobDataType)

This command is sent by the user to get (i.e. to extract from the Stack) the OOB data generated by the Stack itself.

Source

async fn set_oob_data(&mut self, params: &SetOobDataParameters)

This command is sent (by the User) to input the OOB data arrived via OOB communication.

Source

async fn add_devices_to_resolving_list( &mut self, whitelist_identities: &[PeerAddrType], clear_resolving_list: bool, )

This command is used to add devices to the list of address translations used to resolve Resolvable Private Addresses in the Controller.

Source

async fn remove_bonded_device(&mut self, address: BdAddrType)

This command is used to remove a specified device from bonding table

Source

async fn add_devices_to_list( &mut self, list_entries: &[BdAddrType], mode: AddDeviceToListMode, )

This command is used to add specific device addresses to the white and/or resolving list.

Source

async fn additional_beacon_start( &mut self, params: &AdditonalBeaconStartParameters, ) -> Result<(), Error>

This command starts an advertising beacon. It allows additional advertising packets to be transmitted independently of the packets transmitted with GAP advertising commands such as ACI_GAP_SET_DISCOVERABLE or ACI_GAP_SET_LIMITED_DISCOVERABLE.

Source

async fn additional_beacon_stop(&mut self)

This command stops the advertising beacon started with ACI_GAP_ADDITIONAL_BEACON_START.

Source

async fn additonal_beacon_set_data(&mut self, advertising_data: &[u8])

This command sets the data transmitted by the advertising beacon started with ACI_GAP_ADDITIONAL_BEACON_START. If the advertising beacon is already started, the new data is used in subsequent beacon advertising events.

Source

async fn adv_set_config(&mut self, params: &AdvSetConfig)

This command is used to set the extended advertising configuration for one advertising set.

This command, in association with adv_set_scan_response_data, adv_set_advertising_data and adv_set_enable, enables to start extended advertising.

These commands must be used in replacement of set_discoverable, set_limited_discoverable, set_direct_connectable, set_nonconnectable, set_undirected_connectable and set_broadcast_mode that only support legacy advertising.

Source

async fn adv_set_enable<'a>(&mut self, params: &AdvSetEnable<'a>)

This command is used to request the Controller to enable or disbale one or more extended advertising sets.

Source

async fn adv_set_advertising_data(&mut self, params: &AdvSetAdvertisingData<'_>)

This command is used to set the data used in extended advertising PDUs that have a data field

Source

async fn adv_set_scan_response_data( &mut self, params: &AdvSetAdvertisingData<'_>, )

This command is used to provide scan response data used during extended advertising

Source

async fn adv_remove_set(&mut self, handle: AdvertisingHandle)

This command is used to remove an advertising set from the Controller.

Source

async fn adv_clear_sets(&mut self)

This command is used to remove all exisiting advertising sets from the Controller.

Source

async fn adv_set_random_address( &mut self, handle: AdvertisingHandle, addr: BdAddr, )

This command is used to set the random device address of an advertising set configured to use specific random address.

Provided Methods§

Source

async fn init_gap( &mut self, role: Role, privacy_enabled: bool, dev_name_characteristic_len: u8, )

Register the GAP service with the GATT.

This function exists to prevent name conflicts with other Commands traits’ init methods.

Source

async fn set_gap_event_mask(&mut self, flags: EventFlags)

Allows masking events from the GAP.

This function exists to prevent name conflicts with other Commands traits’ set_event_mask methods.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§