Support

BLE Workbench displays peripheral data in a screen hierarchy, according to the natural organization of the data. Service Detail and Characteristic Detail screens are only available to see, after the peripheral is in a connected state. The screen hierarchy consists of the peripherals list, then deepening levels of details based on row selection:

                            • Peripherals List

                                • Peripheral Detail

                                    • Service Detail

                                        • Characteristic Detail

Some peripherals support connections while others do not. If a peripheral supports connections, a connect button will appear on the far side of the peripheral row. The connect button is a circle with a small link inside.

• The connect button supports three different connect states:
  • connectable (tap to connect)
  • connecting (grey fill if attempting)
  • connected (tap to disconnect)

To connect a connectable peripheral, tap the small connect button. Typically the button will briefly transition from connectable (hollow) to attempting to connect (grey filled) to connected (solid filled blue or white).

Occassionally, a peripheral may get “stuck” in a attempting to connect state. Simply tap the button again and the app will send a disconnect command to the peripheral. If after a few attempts the connection cannot be established the peripheral signal strength may be too weak or the peripheral may have additional authentication requirements that the vendor may require. Only attempt to connect to your own peripherals or peripherals you are authorized to manage!

To disconnect a peripheral in a connected or connecting state, simply tap the connect (disconnect) button to return the peripheral to a disconnected (connectable) state.

Some BLE devices require an additional “Bluetooth Pairing Request” step the first time a connection attempt is made to the BLE device from a particular Apple device. After tapping or clicking the connect button, you may notice an alert window or prompt on the screen of the Apple device running BLE Workbench. It should have a title like “Bluetooth Pairing Request”, followed by the name of the peripheral that you just connected to in the app. Typically the alert message would read: “<Peripheral name>” would like to pair with your <device>. One alert button says Pair and the other Cancel. Tap or click Pair button to continue. Once paired like this, future connections to this peripheral should not require the additional pairing step. If the peripheral requires pairing but the cancel button is tapped or clicked in the “Bluetooth Pairing Request”, BLE Workbench may still be able to inspect services and characteristics of the peripheral, but some services and/or characteristics may limit their data, or even prevent access altogether. This is simply due to the peripheral’s restrictions.

An example of this type of restricted behavior is observable when BLE Workbench connects to an iPad or iPhone from your Apple device. If you own the other iPad or iPhone, you should be able to navigate into the Battery Level Service and then the Battery Characteristic. If both devices are signed into the same iCloud account, you should be able to read the Battery charge level and display a green battery showing the percent of charge. If the iPad or iPhone is someone elses, (and you should never connect to someone elses device without permission), even though you will be able to connect and navigate into the Battery Level Characteristic, you will be unable to read the battery level as a value. This is a privacy feature Apple has built into their devices. 

The main screen of BLE Workbench is titled “Peripherals” and will display a list of nearby Bluetooth Low Energy (BLE) devices also commonly referred to as peripherals. The peripherals list can be filtered and sorted in various ways. See the Sort and Filter Help Topics below.

• Each peripheral in the list is represented as a row in the list and has the following features:
  • signal strength icon and signal strength represented as negative decibels integer
  • name and optionally alias
  • optional connect / disconnect button
  • detail (disclosure) button
  • swipe left actions: Set Alias, Hide / Show

The peripherals list will show both nearby peripherals and peripherals that were nearby at one time. To only show the currently nearby peripherals, drag down in the middle of the list just below the title until a spinner appears, then release. This will refresh the peripherals list and only show the nearby devices. Tapping or clicking on a peripheral row or detail (disclosure) button will select this peripheral and display the Peripheral Detail screen. See Peripheral Detail Help Topic.

After selecting a peripheral from the Peripherals list, a Peripheral Detail screen will appear. The peripheral detail is divided into sections and rows. The first section “INFO” shows the familiar peripheral row. The next section “ADVERTISEMENT DATA” shows several dynamic rows. If the peripheral is connected as indicated by a solid connect button, and if the peripheral advertises services, these services will appear under an additional section “SERVICES” below the ADVERTISEMENT DATA section.

Proprietary Services will appear as a long UUID string and industry standardized Services will appear with a human readable name. Tapping a Service row will navigate to a Service Detail screen. See Service Detail Help Topic.

To refresh the Peripheral Detail screen, simply drag down in the middle of the list just below the screen title until a spinner appears, then release. This will refresh the Peripheral Detail screen. If the peripheral has disconnected, the connect button will be hollow and the SERVICES section will be removed.

After selecting a service from the Peripheral Detail’s SERVICE section, a new Service Detail screen will be shown. The service detail screen is also divided into sections. The first section is again, an INFO section showing the selected peripheral row. If the selected Service contains Characteristics, these will be shown in a section labeled CHARACTERISTICS. If the selected Service contains included Services, these will be shown in a section labeled INCLUDED SERVICES.

Proprietary Characteristics will appear as a long UUID string and industry standardized Characteristics will appear with a human readable name. Tapping a Characteristic row will navigate to a Characteristic Detail screen. See Characteristic Detail Help Topic.

To refresh the Service Detail screen, simply drag down in the middle of the list just below the screen title until a spinner appears, then release. This will refresh the Service Detail screen. If the peripheral has disconnected, the connect button will be hollow and the CHARACTERISTICS section will be removed.

After selecting a characteristic from the Service Detail’s CHARACTERISTICS section, a new Characteristic Detail screen will be shown. The characteristic detail screen is also divided into sections. An optional top section may show an image, buttons, or details specific to the characteristic. For example, a Battery Level characteristic will show a battery image indicating the percent of charge. Below the optional top section, a section titled “CHARACTERISTIC” will be shown. This section will have one or more rows showing details of the characteristic, including a unique identifier (CBUUID), optional value, Notify | Indicate, and Debug row. Below the CHARACTERISTIC section, an optional, dynamic section labeled “PROPERTIES” will be shown with the characteristic properties.

If the characteristic supports Notify or Indicate, a special Notify or Indicate button will appear in the upper right corner of the Characteristic Detail screen. Choosing this button will ask the peripheral to either “notify” or “indicate” values. For example if a Heart Rate Measurement Characteristic is shown, choosing the Notify button would update the Characterstic Detail screen and show live heart rate beats per minute.

The Sort menu controls how peripherals are sorted. Peripherals can be sorted by Name or by Signal strength. The sort order is determined by the Order menu item. Order behaves as a toggle.

Sort Order
Order menu item behaves as a toggle. It is either ascending or descending sort order: Order or Order on iOS and iPad, or Order Ascending and Order Descending on macOS. Order determines the sort order of the peripherals.

Sort by Name
If the Name menu item is selected, and Order (Order Ascending on macOS) is shown, the peripherals will be sorted by the peripheral name, with sort ordered A to Z. If the Name menu item is selected, and Order (Order Descending on macOS) is shown, the peripherals will be sorted by the peripheral name, with sort ordered Z to A.

Sort by Signal
If the Signal menu item is selected, and Order (Order Ascending on macOS) is shown, the peripherals will be sorted by the peripheral signal strength, with sort ordered strongest to weakest signal. If the Signal menu item is selected, and Order (Order Descending on macOS) is shown, the peripherals will be sorted by the peripheral signal strength, with sort ordered weakest to strongest signal.

The Filter menu items affect which peripherals will appear in the list. Every discovered or connected peripheral, is first ‘tagged’ with filter attributes. Filter attributes correspond to the filter menu items. A peripheral that is a strong signal strength, connected, and had a name or alias that matches the user’s Search Term would receive the filter attributes: [connected, strong signal, search term]. After all the peripherals are tagged with filter attributes, the selected Filter menu items are then compared with each tagged peripheral. Some Filter menu items are exclusive, like the Hidden menu item, while others are compared across the group.

Filter by Connected and Connectable
If a peripheral is connected, it will be tagged with filter attributes: [connected, connectable]. If a peripheral is not connected but has a connection button, it will be tagged with filter attributes: [connectable]. If neither Connected, nor Connectable menu items are selected, then a peripheral’s [connected, connectable] filter attributes won’t be used in the filter comparison.

Filter by Hidden
The Hidden menu item is exclusive. If the Hidden menu item is selected, only peripherals with a filter attribute [hidden] will appear in the list.

Filter by Search
After choosing the Search menu item, a small window will appear to allow a search term to be entered. Additionally, a button on the far side of the text input field can be toggled to use a case sensitive or case insensitive search. This filter is AND’d with any other selected filters. If a peripheral name or alias matches the search term and case sensitive setting, it would be filter attribute tagged with [search term]. If other selected filters also match according to their rules, this peripheral would appear in the list.

Filter by Signal Strength
Four signal strength filters are available. Signal strength filters are OR’d together with each other and AND’d to the other filters. If all Signal strength menu items are selected or no Signal strength menu items are selected, the signal strength filter would *not* play a role in the filtered peripherals list. If less than all of the Signal strength menu items are selected, only peripherals attribute tagged with one of the selected signal strengths will continue filer evaluation for inclusion in the final filtered list. A peripheral always has a signal strength, and it only ever has one signal strength attribute tag.

Peripherals often begin with a long sequence of characters as a name. This is their unique identifier, known as a UUID. Sometimes after connecting to a peripheral, the name will be updated to show a more memorable name. Either way, the Set Alias action can be used to add a more meaningful alias to a peripheral. To add an alias to a peripheral, begin by slowly swiping from the right side to the left side of a peripheral in the list. This will expose the Set Alias action. Choosing this action will show a simple Set Alias entry form where a new alias can be given to the peripheral. Both the alias and the peripheral name will now appear in the list and be used for comparison if a Search Term filter is used. To remove a given alias, choose the Set Alias action again, and clear any existing alias, then choose Set Alias button to remove the alias.

Sometimes a peripheral appears in the list and is of no interest. Maybe it is someone else’s peripheral. To remove this peripheral from appearing in your list, choose the Hide action. To Hide a peripheral, begin by slowly swiping from the right side to the left side of a peripheral in the list. This will expose the Hide action. Choosing this action will hide this peripheral form the list. To see the list of hidden peripherals, choose Filter, then select the Hidden menu item. To show a hidden peripheral again (move it off the hidden list), swipe from the right side t othe left side of the hidden peripheral to expose the Show action. Choose this action to remove the peripheral from the hidden list and back to the visible list. Selecting only the Hidden filter and no other filters will ensure that all the hidden peripherals will be shown.