Contact Network

Bluetooth

Supported on Android.

Scans and monitors Bluetooth signals in the surrounding environment.

Each Bluetooth record includes the following:

Device Name: The friendly name of the Bluetooth device in proximity. Internally stored as dev_name.

Device Class: The class of the Bluetooth device in proximity, in HEX value. This class determines the type of the device, such as a set-top box, or smartphone. Internally stored as dev_class.

MAC Address: The MAC address of the device. Internally stored as mac.

RSSI: Received signal strength, in dBm. Internally stored as rssi.

Bluetooth Beacons

Supported on Android & iOS.

Choosing this data source will instruct the Avicenna app on Android and iPhone devices to continuously scan for Bluetooth Beacon devices in proximity, and record the relevant beacons.

Basic Concept

Bluetooth Beacons are low-cost external wearable devices which can be carried by participants, attached to physical objects, or placed at specific locations such as rooms. They are powered by a button cell battery and can function from a few months to a few years, depending on their configuration, without any battery replacement.

Beacons are not capable of storing large data or running applications. They only continuously announce their presence in the environment. When the participant's smartphone running the Avicenna app is in their proximity, the app hears the beacon and records its presence. This information later can be used to infer the proximity of the participant to another participant carrying a beacon, or to a specific object (like their car), or a specific room in a building.

While there are many beacon manufacturers globally, the majority of them function based on one of the two popular standards: iBeacon developed by Apple and Eddystone developed by Google. Most beacons support both these standards and can be configured to work as either of them.

For technical reasons, Avicenna only uses the iBeacon standard designed by Apple. Therefore, you should be able to use any beacon with iBeacon support. Avicenna has been successfully tested with beacons manufactured by Kontakt.IO, Accent Systems, and Gimbal, Ltd., though you can choose any other manufacturer as long as their beacon comes with iBeacon support. Note that while Avicenna uses iBeacon, the Bluetooth Beacon data source is recognized and functions as expected both on Android and iPhone devices.

If you want to use a beacon for your Avicenna study, you need to first configure it to operate as iBeacon. Usually, that means using the manufacturer's iPhone or Android app to connect to the beacon and set it to signal as an iBeacon device. At this step, the app will ask you to provide three pieces of information:

• Universally Unique Identifier or UUID: An example is 4D0395FF-6470-44AC-9550-A27B3E6387FD.
• Major Number: A number from 0 to 65535.
• Minor Number: A number from 0 to 65535.

UUID is an ID unique to your study. You can find your study's UUID in the Beacon Mapping tab of the Data Sources page. Your beacon continuously announces this ID, so only participants in your study can find them. Major and Minor together distinguish this beacon from all other beacons you have defined and used in your study. Note that numbers can be specified in decimal or hexadecimal base. UUID is always written in hexadecimal and therefore has a combination of numbers and letters. Major and Minor numbers can be specified either in decimal or hexadecimal. Avicenna always shows the decimal value. When you want to enter these numbers in the beacon manufacturer's app to configure the beacon, make sure you enter the number in the correct base.

Each beacon you use in your study requires a unique combination of Major/Minor number. To calculate these two numbers, you need to specify the following information for the given beacon in Avicenna:

• Team ID: The ID of the team the beacon belongs to. You can think of teams as a few related participants, or the participant and their alters, or physical objects of interest related to the participant. A given study can have up to 4096 teams, each with a unique ID ranging from 0 to 4095.
• Role ID: The ID of the role that the beacon belongs to. A given study can define up to 8 roles, each with a unique ID ranging from 0 to 7. Note that IDs for the similar roles should be unique across teams. For example, if you assign cars as role ID 0, you cannot change their role ID for other teams.
• Subject ID: The ID of the beacon, which distinguishes the beacon from other beacons with the same team and role. A given beacon team/role combination can have up to 131072 beacons, with ID ranging from 0 to 131071.

Given these numbers, Avicenna can provide you with a unique Major/Minor value and a UUID. You can use this information to configure the beacon as an iBeacon.

Assigning Team, Role, and Subject ID to each of your study beacons depends on your study design. Avicenna provides some examples here which can better clarify how you can specify these IDs.

Data Fields

Each Bluetooth beacon record includes the following data:

Device Class: The class of the observed Bluetooth beacon, in HEX value. Android only, iOS records will always store 0. Internally stored as dev_class.

Device Name: The name of the observed Bluetooth beacon, assigned to it while configuring the beacon. Android only, iOS records will always store none. Internally stored as dev_name.

MAC Address: The MAC address of the observed Bluetooth beacon device. Android only, iOS records will always store none. Internally stored as mac.

Payload: The concatenation of Major and Minor value of the observed Bluetooth beacon. Internally stored as payload.

Team ID: The Team ID of the observed Bluetooth beacon. Internally stored as team_id.

Role ID: The Role ID of the observed Bluetooth beacon. Internally stored as role_id.

Subject ID: The Subject ID of the observed Bluetooth beacon. Internally stored as subject_id.

RSSI: Received signal strength, in dBm. Internally stored as rssi.

Destination: The label of the observed Bluetooth beacon, as defined in the Beacon Mapping tab of the Data Sources page of the Researcher Dashboard (more here). When Avicenna server receives a beacon record, prior to storing it in the database, it will check what is the label for the observed beacon, based on its unique set of Team ID/Role ID/Subject ID. This value then is stored together with the beacon record. Internally it's stored as dst.

Designing Beacon-based Studies

When you are designing a study to use Bluetooth Beacons, you should distinguish between two components:

• Participants who install the Avicenna app on their Android or iPhone smartphone and their app is continuously looking for Bluetooth Beacons in proximity.
• Bluetooth Beacons which are configured to announce their presence continuously for any participant in proximity to find them.

It’s important to note that participants and beacons are separate entities, and while you can assign a beacon to each participant, you don’t have to do so. In general, studies using beacons can be grouped into three categories:

The first group includes studies that are focused on capturing the interaction between participants. In such studies, each participant is expected to continuously search for other participants in the vicinity, so they need to have the Avicenna app installed on their smartphone. They are also required to broadcast their presence to other participants. Therefore, they need to carry a Bluetooth Beacon with them at all times. Therefore, the number of beacons in these studies is the same as the number of participants.

The second group includes studies that capture the interaction of participants, and also the interaction between participants and non-participant items. For example, the amount of time participants spend together and the time they spend in different rooms in the building. In this case, similar to the first group, participants need to have the app installed as well as carrying a beacon. Additionally, there should be beacons configured and placed in each room. Therefore, the number of beacons in the study is more than the number of participants.

The third group includes studies that capture the interaction between participants and non-participant items. For example, a study may want to measure the amount of time participants use their bike. In this case, participants need to have the Avicenna app installed to listen for the proximity to the beacons, but they don’t need to carry a beacon themselves. Each object (in this case, bikes) need to have a beacon attached to it. Therefore, the number of beacons and the number of participants are not related. There can be more or fewer beacons than the number of participants.

Regardless of the study design, each beacon and participant part of the study should be assigned a team ID, a role ID, and a subject ID. These numbers are used by Avicenna app to know who is this beacon that is in proximity. The Avicenna app continuously looks for beacons around and records their Team/Role/Subject ID. Therefore, you need to make sure these IDs are unique for each subject (i.e. beacon and subject).

If a given participant is expected to install the app and carry a beacon (as described in the first and second case above), you should assign the same Team/Role/Subject ID to both the participant and their beacon. This way, when the participant’s app scans the environment looking for beacons in proximity, it can recognize the participant’s own beacon and skip recording that as a separate subject.

Beacon Mapping Page

If your study includes Bluetooth Beacon data source, you can manage the beacons defined in Avicenna via the Beacon Mapping tab of the Data Sources page of your Researcher Dashboard, as shown in the image below:

At the top of this page, you can find your study's UUID. For example, in our demo study the UUID is 4d0395ff-6470-44ac-9550-a27b3e6305a1. This will be a different value for your study.

To define a new beacon in Avicenna, click on the Add button on the top right corner of the page. This will open the Add a New Beacon dialog:

In this dialog, you need to specify whether this beacon belongs to a participant or not. We explained above that each beacon in your study can either belong to a participant or not, e.g. it can belong to their bike, or their car, or a particular room, or a non-participant individual.

If you choose the Participant Owned option, then you need to specify which currently enrolled participant, or currently invited participant, owns this beacon. In contrast, choosing Label indicates that this beacon is not owned by a participant, and therefore you can assign a label to it. For example, ROOM01, BIKE_12, or similar. Then you need to assign a team ID, a role ID, and a subject ID to this beacon as well. After entering all the values, pressing Add will create the new beacon mapping in Avicenna.

The image above shows a study with 4 beacon mappings, where 1 of them is for our only participant, and the other 3 are for non-participant beacons. You can see each row contains all the information you need to configure your beacon:

• Study UUID is written on the top of the page. This value is unique for the entire study.
• Beacon name is written in the Name column, e.g. ETH05a10054009a.
• iBeacon major and minor values are written in the Major and Minor columns, respectively. Note that these values are written in HEX. If your beacon manufacturer's app requires decimal values, convert them before using them to configure the beacon.

An Example Study using Beacons

In this section, we describe how you can set up a study which uses Bluetooth Beacons. Here, we assume your study is intended to track the interaction between family members. Your study is planning to recruit 10 subjects, from 3 families, with the following family structure:

• First family: mother, father, son, and daughter.
• Second family: mother, father, and daughter.
• Third family: mother, father, and son.

We consider each family as a team, and assign them a unique ID:

• Team #1 -> First family
• Team #2 -> Second family
• Team #3 -> Third family

Avicenna supports defining the maximum of 4095 teams within the same study. If your study does not require dividing participants into teams, you can simply assign all to team #0.

Within each team (here, a family), we have the following roles, and we assign a unique ID to each role as well:

• Mother -> Role #1
• Father -> Role #2
• Son -> Role #3
• Daughter -> Role #4

Note that not every team is required to have a member for each defined role. In this example, team #2 (second family) does not have any member for role #3 (son), and team #3 (third family) does not have any member for role #4 (daughter).

Each role should be assigned a unique ID across all the teams. If two roles are mutually exclusive between two teams, they cannot have the same role ID. They still are required to have a unique ID. Avicenna supports defining up to 8 roles within each study, marked with ID 0 to ID 7.

Similar to team definition, if your study does not require assigning roles to the participant, you can simply assign role #0 to all participants.

Within each role of each team, there can be 0 or more subjects. Each subject also should have a unique ID, called Subject ID. Note that you can use the same subject ID across roles or teams. For example, the mother of team #1 can have subject ID of 1, the father of team #1 also can have subject ID of #1, and both daughter and son of team #1 also can have subject ID of #1. You might still choose to assign a unique ID to each subject across your study, or at least within each team for more clarity, but that is not necessary.

Avicenna supports defining the maximum of 131,072 subjects within each role of each team, marked with ID 0 to ID 131071.

Participant Enrollment

When you choose to use Bluetooth Beacons to capture interactions between your study participants, you need to assign a team ID, a role ID, and a subject ID to each individual joining your study. These values should be set before the participant joins your study. You can either invite the participant first, and then set these values for them in the Beacon Mapping page (before they use the invitation to join the study), or you can set them directly during the invitation, as explained below.

In our example above, assume the contact information for each family member is as follow:

	First Name	Last Name	Email	Team #	Role #	Subject #
Mother	Mom	Family1	mom@family1.com	1	1	1
Father	Dad	Family1	dad@family1.com	1	2	2
Son	Boy	Family1	boy@family1.com	1	3	3
Daughter	Girl	Family1	girl@family1.com	1	4	4

To invite members of this team to join your study, navigate to Participation -> Invitation page of your study. Then click on the Invite Participants to start creating your invitations.

Note that your study's Enrollment Type does not have to be By Invitation Only in order for you to invite participants. If you have set your study to By Invitation Only, no one else other than invited individuals can join. If you have set your study to be Public, anyone can join the study, whether invited or not.

In the Invitation List dialog, you can enter the list of individuals you want to invite, one invitation per line. You can type the maximum of 100 invitations each time (maximum of 100 lines in the dialog). Each line must include the invitee's email address. You might choose to enter their first name and last name as well, though that is not mandatory.

Additionally, you also have to specify the individual's team/role/subject ID. While this is specified as optional, we do have to include it here. The following lines show the invitations for the above list of participants from team #1:

mom@family1.com,Mom,Family1,{"team": 1, "role": 1, "subject": 1}
dad@family1.com,Dad,Family1,{"team": 1, "role": 2, "subject": 2}
boy@family1.com,Boy,Family1,{"team": 1, "role": 3, "subject": 3}
girl@family1.com,Daughter,Family1,{"team": 1, "role": 4, "subject": 4}

As mentioned above, including first name and last name is not mandatory and you can leave them empty if you choose to. In that case, the invitations would be as follow:

mom@family1.com,,,{"team": 1, "role": 1, "subject": 1}
dad@family1.com,,,{"team": 1, "role": 2, "subject": 2}
boy@family1.com,,,{"team": 1, "role": 3, "subject": 3}
girl@family1.com,,,{"team": 1, "role": 4, "subject": 4}

Note the additional commas between the email address and the ID list for each invitation. Make sure you properly add the commas to indicate that each row includes the email address, skips the first and the last name, and finally includes the required IDs. Pressing the Invite button will add these email addresses to the study's invitation list.

Please make sure you enter the email address for invited participants correctly. Also, participants have to use the email addresses entered here in order to join the study (as opposed to using an alternative or alias address). Avicenna uses the email addresses to identify the participant, check whether they should be allowed to join the study or not, and what team/role/subject they should be assigned to.

When done, you can ask participants to download the Avicenna app on their iPhone or Android smartphone and join the study. If they already have an account with Avicenna and have the app installed, they only have to click on the study's registration URL on their phone in order to join the study. Avicenna app will validate their invitation, enrolls them in the study, and allocates them the correct ID (as specified here). If they do not have an account, when they click on the study registration URL, they will be asked to download the Avicenna app on their phone and create an account. They need to use the email address you have entered while inviting them during the signup.

When a given invited participant has joined the study, their record will be removed from the Invitation list and will be added to the Adherence list. You can follow up on their study progress through the Adherence section. Note that for privacy reasons, the Adherence page does not show the participant's name or email address, and only refers to them using their Avicenna ID (which is different from team ID, role ID, and subject ID specified above). The Avicenna ID will be shown along with their name and email address while they have a pending invitation in the Invitation list. You can use that information prior to their enrollment to manually map Avicenna ID to the email addresses.

Preparing the Beacons

Bluetooth Beacons allow you to capture minute-resolution contact pattern between the participant and any other item of interest, whether other study participants or specific objects or locations. For this purpose, any item you want to be monitored should always be accompanied by a Bluetooth Beacon. For example, if you want to capture the interaction between two participants, both of them should carry a Beacon at all times. Alternatively, if you want to capture the number of times the participant visits a certain room in a building, the participant should carry a Beacon all the time, and another Beacon should be installed in the room. Similarly, if you want to capture the interaction between the participant and their pet, the participant should carry the Beacon and another Beacon should be attached to the pet.

Each Beacon, regardless of where it's mounted or who is carrying it, should be configured with its team ID, role ID, and subject ID. Otherwise, Avicenna app will not capture their proximity and your study will not record any information about the presence of the Beacon. In our example above, each family member should carry their own Beacon, and their Beacon should be configured with participant's unique team/role/subject IDs as described here, prior to being handed out to the participant.

It's important to note that Avicenna captures participants in proximity only using their Beacon. So participants should not exchange their Beacon under any circumstances unless the Beacon is re-configured with their ID. Otherwise, Avicenna assumes the presence of the original owner of the beacon, which can lead to incorrect data.

Configuring Beacons

You need to configure each Beacon with the following information:

• Name
• UUID
• Major
• Minor

You can find all these fields in the Beacon Mapping tab of the Data Sources page of the Researcher Dashboard, as shown above.

Beacons, regardless of their manufacturer, provide support for two common standards: Eddystone by Google and iBeacon by Apple. Almost all Beacons are capable of working as either Eddystone or iBeacon. Avicenna uses iBeacon standard, so while purchasing Beacons, you need to make sure it does support iBeacon.

For each Beacon, we need to perform the following tasks:

1. Turn off all profiles except one iBeacon: Most Beacons are capable of working as iBeacon and Eddystone, even at the same time. Each of these is referred to as a Profile. The Beacon can be configured to specify what information it should continuously broadcast from each active profile.

As mentioned before, Avicenna only works with iBeacon. Therefore, to preserve the battery, you need to turn off all the available profiles, except one iBeacon.

2. Configure the iBeacon profile: As the second step, you need to configure the iBeacon using the Name, UUID, Major, and the Minor value assigned to the given participant. This can be done either through the manufacturer's app, the manufacturer's web-based dashboard, or a combination or both.

The details of how to perform these tasks on each beacon are different for different manufacturers. In this example, we will use Kontakt.IOBeacon Pro. Depending on your needs, you can choose any other Beacon from this company, or any other manufacturer as long as they support iBeacon.

When you purchase a set of Beacons from Kontakt.IO, you will receive an order ID. Start by creating an account on Kontakt.IO's Web Panel. Then, use your order ID to add the Beacons you have purchased to your Web Panel account. This will add all the Beacons you have purchased to the Web Panel.

Each Kontakt.IO Beacon can be identified using a 4-character ID printed on it when you purchase it. There will be one entry per Beacon on the Web Panel, where each entry has the same ID as shown on the Beacon. The following image shows 3 entries on our Web Panel account, for the three Beacon Pros we have purchased.

Click on the first beacon to open the General tab of the beacon. Here, under the Device Profile section, you will see one iBeacon and multiple Eddystone options. Turn off all options except the iBeacon. Also, enter the UUID, Major, and Minor value for the first participant in the related boxes, as shown in the image below. When done, press Save Changes to store the configuration changes. Then, follow these steps for each other beacon as well.

Depending on the software you use, you might have to enter the Major and Minor value in decimal or hexadecimal format. Please make sure you enter the correct format, otherwise, the system will not function correctly.

So far, we have specified the UUID, Major, and Minor of each beacon, but we have not configured the beacon device yet. Configuring a beacon has to be done using Kontakt.IO's Administration App. Moreover, Kontakt.IO does not allow setting the beacon's Name through the Web Panel. Only the app can set the beacon name. In the next step, we will use the Administration App to transfer the UUID/Major/Minor configuration to the Beacon, and also set the Beacon's Name.

After downloading and installing the Administration App on your Android phone, you need to log in to the app using the same credentials you used for Web Portal. This will show you the list of beacons you own, as shown in the following image. You can click on each beacon's ID individually and apply the configuration.

Alternatively, you can choose the Bulk Configuration option to configure all beacons at the same time. Note that the beacons should be in proximity of the phone for the configurations to be transferred correctly. If any beacon failed to be configured, try the operation again to ensure the settings are configured on the beacon properly.

After applying the UUID, Major, and Minor to the beacon, you also have to set the Name of the beacon. For this purpose, click on the beacon ID from the list, and choose BLE Name from the options. In the opened dialog, enter the Name as shown on Avicenna's Beacon Mapping page.

When done, make sure you apply the changes to the beacon again. In the end, your beacon list should show all the values are entered correctly:

When you are done with configuring a beacon, you can give them to the intended participant and ask them to carry it with them at all times during their participation. This way, Avicenna app will capture the presence of any study beacon in the proximity of this participant (hence, the presence of any other participant, object, or room), and also the presence of this participant will be captured by any other phone running Avicenna app (assuming the person is also part of the study).

Defining Surveys

In addition to capturing the contact between subjects in your study, you can configure Avicenna to trigger surveys when a certain type of contact is detected. To achieve this, you should add a Proximity-Triggered triggering logic to your survey, and set the remaining parameters accordingly. You can read more about this here.