Skip to content

Exchanging data between connected devices

CLAID comes with a DataSyncModule and a DataReceiverModule to exchange data (i.e., files) between connected devices. The following figure shows how data synchronization works between two CLAID instances:

You see, that two instances of CLAID are connected via a remote connection. Files from the Smartphone or a Smartwatch will be synchronized with a connected PC or Server via the DataSyncModule and DataReceiverModule respectively, based on configurable synchronization intervalls or conditions, as we will discuss in the following subsections. Note: CLAID also allows to stream data between devices, which is covered in subsequent tutorials.

Prerequisites
  • You have an Android or iOS device running a CLAID application.
  • You have completed the previous tutorial in this series.
  • You understand how to write CLAID configuration files and how to connect Channels.

1. Creating a new CLAID application on your PC or Server to receive data

During data collection, we typically want to transfer data from a mobile device (Smartphone or Smartwatch) to a Server or PC. To create a CLAID application on your PC or Server, please check Tutorial 1.2.

It is also possible to transfer data between two mobile devices, and works analogously as for the PC described below. Simply follow the instructions in Sections 2 and 3 on the second mobile device.

2. Creating a CLAID configuration with two connected hosts

To synchronize data between two applications running CLAID (i.e., two "Hosts"), you need to specify and connect both hosts in the CLAID configuration file. One of the hosts needs to be configured as server, and the other as client. It is also possible for CLAID hosts to act as both server and client. First, we need to define two hosts in the CLAID configuration file:

  1. The first host will be the "Server", which we run on an external PC or Server.
  2. The second host will be the "Smartphone", which we run on the Smartphone.

Once you know the IP address of the "Server", you can adapt the CLAID configuration file as follows:

CLAID configuration file with two hosts

With the configuration below, we configure two hosts, which we will run on the PC and the Smartphone respectively.

  • To make the "Server" host a server, we have to specify the IP address and an arbitrary port of the "Server" host in the "server_config" property. Provide the absolute correct IP address, do not use 127.0.0.1 or localhost!
  • To connect the "Smartphone" host to the "Server" host, we need to specify the "Server" host in the "connect_to" property of the "Smartphone" host. Note, that we do not specify an IP address here. The CLAID runtime will automatically resolve the hostnames to the correct IP addresses at runtime. 
    {
    "hosts": [
        {
            "hostname": "Server",
            "server_config": {
                "host_server_address": "your_ip:1337"
            } 
        },
        {
            "hostname": "Smartphone",
            "connect_to": {
                "host": "Server",
            }
        }
    ]
}

3. Configuring the DataSyncModule and DataReceiverModule

To synchronize data with CLAID, you can use the existing DataSyncModule and DataReceiverModule.

  • The DataSyncModule can be configured to synchronize data at certain times or intervall rates. It will scan a specified folder for new or changed files and synchronize them to the DataReceiverModule running on the other host. Every time a sync is due, the DataSyncModule will post a list of files and their sizes to the DataReceiverModule.
  • The DataReceiverModule will compare the list of files and their sizes with the files on its local storage. For each missing file, or file with different size, it will send a request to the DataSyncModule to transfer it.

Check out the configuration below.

CLAID configuration file with two hosts

With the configuration below, we configure two hosts, which we will run on the PC and the Smartphone respectively.

  • The "Smartphone" host will run the DataSyncModule configured to synchronize data every 5 minutes.
  • The "Server" host will run the DataReceiverModule to receive the synchronized data.

For the synchronization to work, the DataSyncModule and DataReceiverModule need to be connected via two Channels. One Channel is connected from the DataSyncModule to the DataReceiverModule, and one Channel from the DataReceiverModule to the DataSyncModule, to enable bidirectional communication. 

{
    "hosts": [
        {
            "hostname": "Smartphone",
            "connect_to": {
                "host": "Server",
            },
            "modules": [
                  {
                    "type": "DataSyncModule",
                    "id": "DataSyncer",
                    "input_channels": {
                        "FromDataReceiverModuleChannel": "DataReceiverToDataSync"
                    },
                    "output_channels": {
                        "ToDataReceiverModuleChannel": "DataSyncToDataReceiver"
                    },
                    "properties": {
                        "filePath": "%media_dir/files",
                        "syncingSchedule": {
                            "periodic": [
                                {
                                    "period_minutes": 5
                                }
                            ]
                        },
                        "deleteFileAfterSync": "false",
                        "requiresConnectionToRemoteServer": "true",
                        "onlyWhenCharging": false
                    }
                }
            ]
        },
        {
            "hostname": "Server",
            "server_config": {
                "host_server_address": "your_ip:1337"
            },
            "modules": [
                {
                    "type": "DataReceiverModule",
                    "id": "DataReceiver",
                    "input_channels": {
                        "FromDataSyncModuleChannel": "DataSyncToDataReceiver"
                    },
                    "output_channels": {
                        "ToDataSyncModuleChannel": "DataReceiverToDataSync"
                    },
                    "properties": {
                        "storagePath": "/tmp/synced_data"
                    }
                }
            ]
        }
    ]
}

Step-by-step explanation of the configuration file 
{
    "hosts": [
    {
        "hostname": "Smartphone",
        "connect_to": {
            "host": "Server",
        },

The configuration starts with a list of hosts. Each host represents a device running CLAID. Here, we have a host named "Smartphone". A second host "Server" is defined below.

"modules": [
    {
        "type": "DataSyncModule",
        "id": "DataSyncer",

The "Smartphone" host runs a DataSyncModule to synchronize data with the "Server" host.

"input_channels": {
    "FromDataReceiverModuleChannel": "DataReceiverToDataSync"
},
"output_channels": {
    "ToDataReceiverModuleChannel": "DataSyncToDataReceiver"
},

These channels correspond to those defined in the DataReceiverModule, allowing bidirectional communication.

"properties": {
    "filePath": "%media_dir/files",
    "syncingSchedule": {
        "periodic": [
            {
                "period_minutes": 5
            }
        ]
    },
    "deleteFileAfterSync": "false",
    "requiresConnectionToRemoteServer": "true",
    "onlyWhenCharging": false
}

These properties configure the DataSyncModule:

  • filePath: Where to find files to sync. The %media_dir is a special variable that will be replaced with the path to the media directory of the CLAID application. This media dir is typically under /sdcard/Android/media/your.app.package.name/ on Android/WearOS or in the App's document directory on iOS.
  • syncingSchedule: How often to sync (every 5 minutes). You can also specify more sophisticated rules, e.g., only synchronize on certain days of the week or only synchronize during certain hours. Check out Schedule for more details.
  • deleteFileAfterSync: Whether to delete local files after they were synced successfully (DataReceiverModule has to acknowledge receival).
  • requiresConnectionToRemoteServer: Whether a connection to the server is required for operation. If true, then the DataSyncModule will check if the "Smartphone" host is currently connected to the "Server" host. If not, it will not trigger a sync. This can be false, if the DataSyncModule and DataReceiverModule are running on the same host.
  • onlyWhenCharging: If true, then a synchronization will only be performed when the device is plugged in for charging. Only relevant for mobile devices.
{
    "hostname": "Server",

The second host is the "Server" host.

"server_config": {
    "host_server_address": "your_ip:1337"
},

This enables the host to act as a server. The host_server_address is the IP address and port where the server will listen for incoming connections. Note: Each CLAID host can act as both server and client, depending on the configuration.

"modules": [
    {
        "type": "DataReceiverModule",
        "id": "DataReceiver",

The modules array lists the modules to be loaded on this host. Here, we're configuring a DataReceiverModule with the ID "DataReceiver". The DataReceiverModule is used to receive data from the DataSyncModule on the Smartphone.

"input_channels": {
    "FromDataSyncModuleChannel": "DataSyncToDataReceiver"
},
"output_channels": {
    "ToDataSyncModuleChannel": "DataReceiverToDataSync"
},

These define the input and output channels for the module. The DataReceiverModule receives data on the "DataSyncToDataReceiver" channel and can send data back on the "DataReceiverToDataSync" channel. These two channels enable bidirectional communication between the two Modules.

"properties": {
    "storagePath": "/tmp/synced_data"
}

This specifies where the received data will be stored on the server. Note, that all received data is stored according to the user name of the "Smartphone" host. Under /tmp/synced_data/, there will be a folder with the user name of the "Smartphone" host. If multiple CLAID applications are running the same host but with a different user name, the data will be stored in different subfolders.

As you can see, the DataSyncModule has multiple properties which you can specify. Check out the description of each property below:

Properties of the DataSyncModule
  • filePath: Path to a folder which shall be synchronized.
  • syncingSchedule: How often to sync (every 5 minutes). You can also specify more sophisticated rules, e.g., only synchronize on certain days of the week or only synchronize during certain hours. Check out Schedule for more details.
  • deleteFileAfterSync: Whether to delete local files after they were synced successfully (DataReceiverModule has to acknowledge receival).
  • requiresConnectionToRemoteServer: Whether a connection to the server is required for operation. If true, then the DataSyncModule will check if the "Smartphone" host is currently connected to the "Server" host. If not, it will not trigger a sync. This can be false, if the DataSyncModule and DataReceiverModule are running on the same host.
  • onlyWhenCharging: If true, then a synchronization will only be performed when the device is plugged in for charging. Only relevant for mobile devices.

Now, copy the configuration file to both the Smartphone and the PC. Once you run it, you should see files being synchronized from the Smartphone to the PC.

Important: Both hosts always need to have the same configuration file! This is required so that both hosts know of each other and can connect. Which part of the configuration is used on each device depends on the hostname you specify when starting CLAID.

Cannot establish a connection?

If the devices you want to connect with each other are not in the same physical network (e.g., same Wifi) as the device from which you want to connect, you might have to open ports and add firewall rules for the device running the CLAID application acting as Server. You might have to set up port forwarding, if you connect externally.

Also, we found that some Android or iOS Emulators sometimes also have problems with the firewall rules, making it challenging to connect to CLAID running on the Emulator from outside.

Special note for macOS: If you are running on macOS, sometimes it doesn't work due to some firewall limitations. When you start CLAID on your device, macOS should show a dialog and ask you whether you want to allow your CLAID application to accept incoming connections. Sometimes, however, macOS does not show this dialog. We found that if we put a CLAID application folder on the Desktop under macOS, the OS will not show the firewall dialog. Do not put a CLAID application/project folder on the Desktop under macOS.

4. Synchronizing data from multiple users

The DataReceiverModule on the Server automatically stores received files in folders according to the user name which you have specified in Tutorial 2.1. If you install your CLAID App on multiple devices (e..g, smartphones), make sure to set an unique user identifier on each. Keep in mind the differences between hosts and users.

Difference between host and user
  • A host is simply a configuration for a certain entity. Multiple devices can execute the same host. A host is simply one group of entities with the same configuration.
  • A host is a unique identifier for multiple devices/users running a host. For example, in a study, multiple users can run our defined "Smartphone" host.