diff --git a/README.md b/README.md index 0adeba3..623f466 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,9 @@ The documentation site for [RADAR-base](https://github.com/RADAR-base), published to GitHub Pages at . -Documentation is **not written here**. Each project's pages live in that project's own -repository, next to the code they describe. This site fetches them at build time, so: +Component documentation is **not written here**. Each component's pages live in that +component's own repository, next to the code they describe. This site fetches them at build +time, so: - maintainers decide what their project's documentation contains, in their own repository, reviewed in their own pull requests; @@ -12,6 +13,13 @@ repository, next to the code they describe. This site fetches them at build time can switch between versions; - the site rebuilds itself when a project releases, when its docs change, and nightly. +The exception is the material that does not belong to any one component — the platform +overview and FAQ, and the client and participant guides in `content/client` and +`content/participant`. Those pages are written and reviewed here. The guides were copied from +[radar-base.org/docs](https://radar-base.org/docs/) on 3 September 2026, and each one ends with +a line naming the page it came from, so a change made on either site can be carried to the +other. + ## Adding a repository **1. Put the documentation in your repository.** Create a `docs/` folder and write ordinary @@ -88,7 +96,9 @@ Everything the fetch step writes is generated output and is not committed: `docs | Path | Purpose | | --- | --- | | [`repos.yml`](repos.yml) | Which repositories are published, and where | -| [`content/platform/`](content/platform/) | Cross-project documentation, written here | +| [`content/platform/`](content/platform/) | Cross-component documentation, written here | +| [`content/client/`](content/client/) | Client documentation — the apps and devices a study runs on | +| [`content/participant/`](content/participant/) | Participant-facing guides | | [`scripts/fetch-docs.mjs`](scripts/fetch-docs.mjs) | Fetches and normalises each project's docs | | [`templates/`](templates/) | Files that project repositories copy into their own repo | | [`overrides/`](overrides/) | Optional stand-in manifest for a project that has not adopted one | diff --git a/content/client/img/passive-app-prmt-main-activity-461x1024.jpg b/content/client/img/passive-app-prmt-main-activity-461x1024.jpg new file mode 100644 index 0000000..31d95b0 Binary files /dev/null and b/content/client/img/passive-app-prmt-main-activity-461x1024.jpg differ diff --git a/content/client/img/phone-data-sensors-ios-prmt-app-android-sensor-comparison.png b/content/client/img/phone-data-sensors-ios-prmt-app-android-sensor-comparison.png new file mode 100644 index 0000000..328f62b Binary files /dev/null and b/content/client/img/phone-data-sensors-ios-prmt-app-android-sensor-comparison.png differ diff --git a/content/client/img/questionnaire-app-armt-start-scrn-e1664543291170.png b/content/client/img/questionnaire-app-armt-start-scrn-e1664543291170.png new file mode 100644 index 0000000..8edd9ab Binary files /dev/null and b/content/client/img/questionnaire-app-armt-start-scrn-e1664543291170.png differ diff --git a/content/client/img/questionnaire-app-armt-start-scrn2.png b/content/client/img/questionnaire-app-armt-start-scrn2.png new file mode 100644 index 0000000..92c64e2 Binary files /dev/null and b/content/client/img/questionnaire-app-armt-start-scrn2.png differ diff --git a/content/client/img/rest-source-auth-image-1.png b/content/client/img/rest-source-auth-image-1.png new file mode 100644 index 0000000..e35991a Binary files /dev/null and b/content/client/img/rest-source-auth-image-1.png differ diff --git a/content/client/img/rest-source-auth-image-2-1024x675.png b/content/client/img/rest-source-auth-image-2-1024x675.png new file mode 100644 index 0000000..b92fa31 Binary files /dev/null and b/content/client/img/rest-source-auth-image-2-1024x675.png differ diff --git a/content/client/img/rest-source-auth-image-2.png b/content/client/img/rest-source-auth-image-2.png new file mode 100644 index 0000000..6129fda Binary files /dev/null and b/content/client/img/rest-source-auth-image-2.png differ diff --git a/content/client/img/rest-source-auth-image-3.png b/content/client/img/rest-source-auth-image-3.png new file mode 100644 index 0000000..57ff1ea Binary files /dev/null and b/content/client/img/rest-source-auth-image-3.png differ diff --git a/content/client/img/rest-source-auth-image-4.png b/content/client/img/rest-source-auth-image-4.png new file mode 100644 index 0000000..b5e7a2a Binary files /dev/null and b/content/client/img/rest-source-auth-image-4.png differ diff --git a/content/client/img/rest-source-auth-image-5.png b/content/client/img/rest-source-auth-image-5.png new file mode 100644 index 0000000..8afc3d4 Binary files /dev/null and b/content/client/img/rest-source-auth-image-5.png differ diff --git a/content/client/img/rest-source-auth-image.png b/content/client/img/rest-source-auth-image.png new file mode 100644 index 0000000..fa8abe4 Binary files /dev/null and b/content/client/img/rest-source-auth-image.png differ diff --git a/content/client/img/supported-devices-apple-watch-int-dev-500x286.png b/content/client/img/supported-devices-apple-watch-int-dev-500x286.png new file mode 100644 index 0000000..1b56789 Binary files /dev/null and b/content/client/img/supported-devices-apple-watch-int-dev-500x286.png differ diff --git a/content/client/img/supported-devices-biovotion-500x286.png b/content/client/img/supported-devices-biovotion-500x286.png new file mode 100644 index 0000000..005d6f2 Binary files /dev/null and b/content/client/img/supported-devices-biovotion-500x286.png differ diff --git a/content/client/img/supported-devices-e4-1-500x286.png b/content/client/img/supported-devices-e4-1-500x286.png new file mode 100644 index 0000000..55bac56 Binary files /dev/null and b/content/client/img/supported-devices-e4-1-500x286.png differ diff --git a/content/client/img/supported-devices-faros-500x286.png b/content/client/img/supported-devices-faros-500x286.png new file mode 100644 index 0000000..6cb8a53 Binary files /dev/null and b/content/client/img/supported-devices-faros-500x286.png differ diff --git a/content/client/img/supported-devices-fitbit-500x286.png b/content/client/img/supported-devices-fitbit-500x286.png new file mode 100644 index 0000000..55e6a5b Binary files /dev/null and b/content/client/img/supported-devices-fitbit-500x286.png differ diff --git a/content/client/img/supported-devices-garmin-int-dev-500x286.png b/content/client/img/supported-devices-garmin-int-dev-500x286.png new file mode 100644 index 0000000..9bba255 Binary files /dev/null and b/content/client/img/supported-devices-garmin-int-dev-500x286.png differ diff --git a/content/client/img/supported-devices-oura-ring-int-dev-500x286.png b/content/client/img/supported-devices-oura-ring-int-dev-500x286.png new file mode 100644 index 0000000..34c2069 Binary files /dev/null and b/content/client/img/supported-devices-oura-ring-int-dev-500x286.png differ diff --git a/content/client/img/supported-devices-pebble-500x286.png b/content/client/img/supported-devices-pebble-500x286.png new file mode 100644 index 0000000..97a85c7 Binary files /dev/null and b/content/client/img/supported-devices-pebble-500x286.png differ diff --git a/content/client/img/supported-devices-polar-vantage-v3-rb1-e1732283578255-500x286.jpg b/content/client/img/supported-devices-polar-vantage-v3-rb1-e1732283578255-500x286.jpg new file mode 100644 index 0000000..e87a711 Binary files /dev/null and b/content/client/img/supported-devices-polar-vantage-v3-rb1-e1732283578255-500x286.jpg differ diff --git a/content/client/img/supported-devices-rb-polar-h10-chest-strap-ecg-500x286.jpg b/content/client/img/supported-devices-rb-polar-h10-chest-strap-ecg-500x286.jpg new file mode 100644 index 0000000..f9d0a6c Binary files /dev/null and b/content/client/img/supported-devices-rb-polar-h10-chest-strap-ecg-500x286.jpg differ diff --git a/content/client/img/supported-devices-screenshot-from-2024-03-05-18-51-54.png b/content/client/img/supported-devices-screenshot-from-2024-03-05-18-51-54.png new file mode 100644 index 0000000..21ef77b Binary files /dev/null and b/content/client/img/supported-devices-screenshot-from-2024-03-05-18-51-54.png differ diff --git a/content/client/intro.md b/content/client/intro.md new file mode 100644 index 0000000..4cc241c --- /dev/null +++ b/content/client/intro.md @@ -0,0 +1,33 @@ +--- +title: Client documentation +slug: / +sidebar_position: 1 +description: The apps and devices a RADAR-base study runs on, and what each of them collects. +--- + +# Client documentation + +The apps and devices a study runs on: what they collect, which hardware is supported, and how +participants are connected to third-party wearable accounts. + +- **[RADAR-Rest-Source-Auth](./rest-source-auth.md)** — authorising RADAR-base to collect from + third-party wearable APIs (Oura, Fitbit, Garmin) through the REST authorizer. +- **[Questionnaire app (aRMT)](./questionnaire-app.md)** — the configurable questionnaire app + for active tasks, on Android and iOS. +- **[Passive app (pRMT)](./passive-app.md)** — background collection from phone sensors and + from wearables paired over Bluetooth. +- **[Phone data sensors](./phone-data-sensors.md)** — what each supported phone sensor records, + and where its Avro schema is defined. +- **[Supported devices](./supported-devices.md)** — the wearables integrated into the platform + and the data types each one contributes. + +For how these pieces fit into the platform as a whole, see +[Concepts and components of RADAR-base](/platform/concepts-and-components). Participant-facing +material is under [Participant](/participant/). + +:::note Copied from the RADAR-base website +The pages in this section were copied from +[radar-base.org/docs](https://radar-base.org/docs/) on 3 September 2026, so they can be read, +searched and versioned alongside the rest of this site. Each page links back to the version it +came from. +::: diff --git a/content/client/passive-app.md b/content/client/passive-app.md new file mode 100644 index 0000000..2728130 --- /dev/null +++ b/content/client/passive-app.md @@ -0,0 +1,21 @@ +--- +title: "Passive app (pRMT)" +sidebar_position: 4 +description: "The passive app that collects background sensor data from the phone and paired wearables." +--- + +The RADAR-base Passive Mobile App (pRMT App) is the hub for collecting background sensor data and provides data streams from both on-phone sensors (below) and the capability to collect data from a number of wearable devices. New wearable devices can readily be connected to the passive app as plugins using a vendor SDK. + +- Collect data from native phone sensors and APIs +- Plugin integration of peripheral wearable devices using Bluetooth + - Empatica E4, Faros +- Easy onboarding via QR code scanning +- Real-time streaming +- Customizable plugins per study +- Fault tolerance on the app + +![](./img/passive-app-prmt-main-activity-461x1024.jpg) + +--- + +_This page was copied from [Passive app (pRMT)](https://radar-base.org/docs/prmt-app/) on the RADAR-base website (3 September 2026). If you change it here, change it there too._ diff --git a/content/client/phone-data-sensors.md b/content/client/phone-data-sensors.md new file mode 100644 index 0000000..3ca1f82 --- /dev/null +++ b/content/client/phone-data-sensors.md @@ -0,0 +1,161 @@ +--- +title: "Phone data sensors" +sidebar_position: 5 +description: "What each phone sensor the passive app supports records, and where its schema is defined." +--- + +The RADAR-base Passive Mobile App is the hub for collecting background sensor data and provides data streams from both on-phone sensors (below) and the capability to collect data from a number of wearable devices. New wearable devices can readily be connected to the passive app as plugins using a vendor SDK. + +## RADAR-base Support for Android + +The boxes below contain descriptions of available passive phone sensors. Besides the phone sensors we also support the data sensors of an increasing list of devices. For the current overview, please see the [Supported Devices](/client/supported-devices). + +The schemas with all data fields retrieved from the smartphone sensors can be found here: [https://github.com/RADAR-CNS/RADAR-Schemas/tree/master/commons/passive/phone](https://github.com/RADAR-CNS/RADAR-Schemas/tree/master/commons/passive/phone) + +Default sampling rates [https://github.com/RADAR-base/radar-commons-android/tree/master/plugins/radar-android-phone](https://github.com/RADAR-base/radar-commons-android/tree/master/plugins/radar-android-phone) + +### Relative location + +Collects the relative degrees of latitude and longitude data from GPS and/or the Android Network Location Provider (using cell tower and WiFi signals). To ensure participants privacy, the absolute location is converted to a location relative to an unspecified reference offset. No absolute location data is streamed to or stored on the server. Besides the coordinates, the module also collects altitude (relative), speed, bearing and the accuracy of the location. + +Location data can be used to derive information about the mobility of participants and determine commonly visited locations. + +_Avro schema:_ [phone\_relative\_location](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_relative_location.avsc) + +#### Note on relative coordinates + +A problem caused by randomly shifting coordinates to a different origin, is that distances between these coordinates cannot be calculated accurately. A degree travelled at the equator is a different distance than in the Arctic. The longitude is made relative to the first longitude reported for that participant. The latitude however, is only shifted by a random number of degrees between -4 and 4. This means that for a received relative location, the actual location will be within a 8 degree latitude band around the earth. The 8 degree latitude band corresponds to a UTM latitude band, which allows for a good approximation of the actual distance. See for more information: [https://en.wikipedia.org/wiki/Universal\_Transverse\_Mercator\_coordinate\_system](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system) + +### Acceleration + +Collects the raw acceleration values from the 3-axis accelerometer with the gravitational constant (g ≈ 9.81m/s) as unit. By default, the values are collected in roughly 200 millisecond intervals. The values include the gravitational acceleration. For a device at rest, the magnitude of acceleration is therefore approximately 1g. The acceleration can be used to assess general activity as well as analyse movement in more detail, e.g. the gait of participants. + +_Avro schema:_ [phone\_acceleration](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_acceleration.avsc) + +### Gyration + +Collects the raw gyration values from the 3-axis gyroscope in radians per second (rad/s). By default, the values are collected in 200 millisecond intervals. The gyration reports the rotation of the device over one of the three axes. The gyration can be used to analyse movement, e.g. the gait of participants. + +_Avro schema:_ [phone\_gyroscope](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_gyroscope.avsc) + +### Magnetic Field + +Collects the raw magnetic field from the 3-axis magnetometer. By default, the values are collected in 200 millisecond intervals and have micro Tesla (µT) as unit. Without the presence of other magnets, the sensor measures the earth magnetic field. This can be used, together with the acceleration and gyration, to determine the position of the device. + +_Avro schema:_ [phone\_magnetic\_field](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_magnetic_field.avsc) + +The acceleration, gyration and magnetic field sensors follow the Android sensor coordinate system: [https://developer.android.com/guide/topics/sensors/sensors\_overview.html#sensors-coords](https://developer.android.com/guide/topics/sensors/sensors_overview.html#sensors-coords) + +### Step count + +Reports the number of steps taken since the previous step count record. In most cases the number is one, which means that every single step will produce a record. The phone derives the step count either from the accelerometer and magnetometer or gyroscope, depending on the availability. The step count can be used as a generic proxy for activity and to approximate distance walked. + +_Avro schema:_ [phone\_step\_count](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_step_count.avsc) + +### Light + +Reports the light intensity from the light sensor in luminous flux per unit area (illuminance, lx). The illuminance is captured if the value changes. This means that when e.g. the light sensor is covered, no values are reported after an initial 0 lx. The light intensity can be used to determine whether the participant is inside in a dark room (e.g. bedroom), illuminated room or outside. + +_Avro schema:_ [phone\_light](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_light.avsc) + +### Bluetooth devices + +Collects the number of paired and nearby Bluetooth devices. By default, the data is collected every hour. As most phones have Bluetooth, the number of nearby Bluetooth is a proxy for the number of people are in the vicinity of the participant. This should be used with care however, because also most other, non-person bound, devices have Bluetooth capabilities. For instance nearby printers and laptops are also counted. + +_Avro schema:_ [phone_bluetooth_devices](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_bluetooth_devices.avsc) + +### Activity recognition events + +The app subscribes to Android’s Activity Recognition API, which emits events when the operating system detects a change in the participant’s activity. Each event includes a classification and a confidence level. Activity classifications include walking, running, on a bicycle, in a vehicle, on foot, tilting, and still. No raw motion or sensor data is recorded by this plug-in. Only the high-level activity classifications produced by the operating system are recorded, in real time as the OS detects transitions. + +_Avro schema_: [google_activity_transition_event](https://github.com/RADAR-base/RADAR-Schemas/blob/9e7e60d5bacefe8be2bc76eb9b9d7d4546cda21b/commons/passive/google/google_activity_transition_event.avsc) + +### Sleep events + +The app subscribes to Android’s Sleep API, which provides on-device sleep classification derived from the phone’s own sensors. The plug-in receives two kinds of event: sleep classifications, which indicate whether the participant is asleep, awake, or in a particular sleep state, and segment events that mark the start and end of a sleep period. No raw sensor data is recorded by this plug-in. Only the classifications produced by the operating system are recorded, delivered as the OS detects changes. + +_Avro schema_: [google_sleep_segment_event](https://github.com/RADAR-base/RADAR-Schemas/blob/9e7e60d5bacefe8be2bc76eb9b9d7d4546cda21b/commons/passive/google/google_sleep_segment_event.avsc) and [google_sleep_classification_event](https://github.com/RADAR-base/RADAR-Schemas/blob/9e7e60d5bacefe8be2bc76eb9b9d7d4546cda21b/commons/passive/google/google_sleep_classify_event.avsc) + +### Interaction state + +Collects the phone interaction state from the Android system. Every phone lock (standby), unlock and shutdown is recorded from respectively the ACTION\_SCREEN\_OFF, ACTION\_USER\_PRESENT and ACTION\_SHUTDOWN intents broadcasted by the system. Also the phone startup is collected by listening for the first action since a shutdown. + +This data can be used to retrieve the total time the phone was used per time period. In conjunction with the application usage, this gives a complete view of the participants phone use. + +_Avro schema:_ [phone\_user\_interaction](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_user_interaction.avsc) + +### Application usage + +Collects opening and closing of installed phone applications. To be more specific, this module listens for the ‘move to foreground’ and ‘move to background’ events for every application. For every event, the package name of the app and event type is registered. The app category, as given by the Google Play Store, is added to the record in the Kafka backend. In addition, the package name can be removed to protect the privacy of the participant. + +The application usage events give insight in the app use of the participant. Metrics like number of apps used and total app usage time per category can be derived from this data. + +_Avro schema:_ [phone\_usage\_event](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_usage_event.avsc) + +### Call log + +Collects ingoing and outgoing calls. The duration of each call, the phone number of the caller and whether the caller is a contact is captured. The phone numbers of callers are hashed, such that the actual numbers are concealed. Also the actual call audio is not stored. + +The call log provides a measure for communication and social interaction. Metrics like the number of different contacted persons can be derived. + +_Avro schema:_ [phone\_call](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_call.avsc) + +### SMS log + +Collects received and send text messages. The length of the message, the phone number of the sender/receiver and whether the sender/receiver is a contact is captured. In addition, the number of unread messages is, by default, collected every day. The phone numbers of callers are hashed, such that the actual numbers are concealed. Also the actual content of the message is not stored. + +Similarly to the call log, the SMS log provides a measure for communication and social interaction. Note that the SMS log does not include messages send via other messaging services. + +_Avro schema:_ [phone\_sms](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_sms.avsc), [phone\_sms\_unread](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_sms_unread.avsc) + +### Contact list + +Collects the current number of contacts in the phone’s contact list and the changes since the previous check. By default, the data is collected every day. This only includes the phone’s native contact application. + +Tracking the number of contacts can be used to monitor new social interactions a participant might have had. + +_Avro schema:_ [phone\_contact\_list](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_contact_list.avsc) + +### Battery level + +Collects the phone battery level and charging status upon change. It can for instance be used to help determine when the participant is traveling and when he/she is home, depending on the charging status. The battery level is only reported when it changes. + +_Avro schema:_ [phone\_battery\_level](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/phone/phone_battery_level.avsc) + +### Local Weather + +Plug-in ‘radar-android-weather’. + +Reports the current local weather conditions. By default, the data is collected every 3 hours from the OpenWeatherMap API. The phone GPS or network coordinates are used to request data for the location. The following weather information is captured: + +• ambient temperature in degrees Celsius (C) + +• atmospheric pressure in hectoPascal (hPa) + +• humidity in percentage (%) + +• cloudiness in percentage (%) + +• precipitation in millimeter rain/snow (mm) + +• condition type + +• sunrise and sunset in minutes after midnight (to calculate total minutes of daylight) + +The weather conditions can be used to relate participant activity and/or mood to outside conditions. + +Note: this data is sensitive, as it can be used in combination with e.g. relative location to improve the approximation of the participants location. + +_Avro schema:_ [local\_weather](https://github.com/RADAR-CNS/RADAR-Schemas/tree/master/commons/passive/weather/local_weather.avsc) + +Information on the pRMT application and connected server. Used for monitoring the connection. + +## RADAR-base Support for iOS + +Separate **Android** and **iOS** versions of the Passive Data Collection app have been developed as part of RADAR-base, however, there are substantial differences in the mobile sensors available on iOS, in particular, these may be more sparse in iOS due to lack of background collection capabilities: + +![](./img/phone-data-sensors-ios-prmt-app-android-sensor-comparison.png) + +--- + +_This page was copied from [Phone data sensors](https://radar-base.org/docs/4048-2/) on the RADAR-base website (3 September 2026). If you change it here, change it there too._ diff --git a/content/client/questionnaire-app.md b/content/client/questionnaire-app.md new file mode 100644 index 0000000..a4b36b2 --- /dev/null +++ b/content/client/questionnaire-app.md @@ -0,0 +1,21 @@ +--- +title: "Questionnaire app (aRMT)" +sidebar_position: 3 +description: "The configurable questionnaire app for active tasks, on Android and iOS." +--- + +RADAR-base includes a fully configurable questionnaire mobile application for the delivery of active tasks: + +- Support on both [**Android**](https://play.google.com/store/apps/details?id=org.phidatalab.radar_armt&hl=en) (minimum version Android 6) and [**iOS**](https://apps.apple.com/gb/app/radar-active-rmt/id1483953055) (minimum version iOS 11) +- Simple configuration of new questionnaires +- Firebase Cloud Messaging remote notifications to inform when to complete questionnaires and tasks +- Simple configurable schedules for questionnaire regimens +- Spoken questionnaire audio sampling capture + +![](./img/questionnaire-app-armt-start-scrn-e1664543291170.png) + +![](./img/questionnaire-app-armt-start-scrn2.png) + +--- + +_This page was copied from [Questionnaire app (aRMT)](https://radar-base.org/docs/questionnaire-app/) on the RADAR-base website (3 September 2026). If you change it here, change it there too._ diff --git a/content/client/rest-source-auth.md b/content/client/rest-source-auth.md new file mode 100644 index 0000000..fb1059e --- /dev/null +++ b/content/client/rest-source-auth.md @@ -0,0 +1,53 @@ +--- +title: "RADAR-Rest-Source-Auth" +sidebar_position: 2 +description: "Authorising RADAR-base to collect from third-party wearable APIs — Oura, Fitbit and Garmin." +--- + +## REST-Authorizer authentication procedure (for wearables like Oura, Fitbit and Garmin) + +The RADAR-REST-Source-Auth is an application to get authorization from users to access their data through 3rd party APIs (e.g. Oura, FitBit, Garmin). Mainly supports OAuth2 Authorization code flow to request authorization and processes the returned authorization code to add new entries of users for data collection. It creates new users and adds properties compatible with and required by the [RADAR REST and Fitbit connectors](https://github.com/RADAR-base/RADAR-REST-Connector). + +``` +Login to https:///rest-sources/authorizer/login +``` + +Steps – + +1\. Create Subject On Management Portal (or via Redcap should be done automatically) + +2\. Set up the wearable (Fitbit/Garmin/Oura) email and password (no need if the participant is doing this themselves) + +3\. Go to the authoriser, log in with your management portal credentials and Select your project. + +![](./img/rest-source-auth-image.png) + +4\. Select the wearable source type + +![](./img/rest-source-auth-image-2-1024x675.png) + +5\. Check the subject Id and external ID (e.g. redcap Id) that you want to pair the Device for. Check the Authorized Status is “Unset” in yellow. + +![](./img/rest-source-auth-image-5.png) + +6\. Then select the Attach+ icon at the right end of the subject row under the Actions column. + +![](./img/rest-source-auth-image-2.png) + +7\. Input the start and end dates + +8\. Now, you can either Authorize yourself if you have the participant’s Wearable account login credentials, or you can Generate a URL to send to the participant to log in themselves. + +![](./img/rest-source-auth-image-4.png) + +9\. This will open the wearable device vendor-specific account login screen. Enter the participant’s wearable device account login credentials. Select all the scopes required and grant the permissions, after which you will be redirected back to the authorizer and the Authorized Status for the subject will now be “Yes” in green. + +![](./img/rest-source-auth-image-3.png) + +10\. After this, you can also de-authorize the subject with the red detach button (for example, if they change their wearable account or leave the study), or you can reset the user (for example, to re-pull all the data between particular dates or to change the start and end dates) with the blue reset button under Actions. + +![](./img/rest-source-auth-image-1.png) + +--- + +_This page was copied from [RADAR-Rest-Source-Auth](https://radar-base.org/docs/radar-rest-source-auth/) on the RADAR-base website (3 September 2026). If you change it here, change it there too._ diff --git a/content/client/supported-devices.md b/content/client/supported-devices.md new file mode 100644 index 0000000..baf8446 --- /dev/null +++ b/content/client/supported-devices.md @@ -0,0 +1,197 @@ +--- +title: "Supported devices" +sidebar_position: 6 +description: "The wearables and devices integrated into the platform, and the data each one contributes." +--- + +Devices integrated into the RADAR-base platform. See [Table of Data Types](https://radar-base.github.io/RADAR-Schemas/) and [RADAR-base schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons) for more comprehensive details of data types collected. + +![](./img/supported-devices-oura-ring-int-dev-500x286.png) + +## Oura Ring Devices + +Finger Worn + +Activity\ +Heart rate\ +Sleep\ +Stress tracking\ +Readiness Score\ +SpO2\ +Temperature + +RADAR-base Integration: via REST-API Connector + +[RADAR-base Oura Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/connector/oura) + +![](./img/supported-devices-apple-watch-int-dev-500x286.png) + +## Apple Watch Devices (and iPhones) + +Wrist Worn + +Activity\ +Heart rate\ +Sleep\ +HRV\ +SpO2\ +Temperature + +RADAR-base Integration: via Active App HealthKit Plugin + +[RADAR-base Healthkit Spec.](https://github.com/RADAR-base/RADAR-Schemas/blob/master/specifications/active/aRMT-healthkit-1.0.0.yml) + +![](./img/supported-devices-garmin-int-dev-500x286.png) + +## Garmin Devices + +Wrist Worn + +Activity\ +Heart rate\ +Sleep\ +Stress tracking\ +Vo2 max\ +Body Battery\ +SpO2 (night time and on-demand)\ +Respiration Rate + +RADAR-base Integration: via REST-API Connector + +[RADAR-base Garmin Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/push/garmin) + +![](./img/supported-devices-fitbit-500x286.png) + +## FitBit Devices + +Wrist worn + +Steps\ +Heart rate, HRV (PPG)\ +Sleep\ +Temperature\ +Irregular Heart Rate + +RADAR-base Integration: via REST-API Connector + +[RADAR-base FitBit Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/connector/fitbit) + +![](./img/supported-devices-polar-vantage-v3-rb1-e1732283578255-500x286.jpg) + +## Polar Vantage V3 + +**Polar Vantage V3** + +Wrist worn + +Raw acceleration\ +Steps\ +Heart rate (PPG)\ +PP-interval in ms\ +Wrist ECG\ +Blood volume pulse (PPG)\ +Sleep stages\ +Temperature + +RADAR-base Integration: via Passive App (pRMT) + +[RADAR-base Polar Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/polar) + +![](./img/supported-devices-rb-polar-h10-chest-strap-ecg-500x286.jpg) + +## Polar H10 Heart Rate Sensor + +**Polar H10 Sensor** + +Chest worn + +Raw acceleration\ +Heart rate (PPG)\ +RR-interval in ms + +RADAR-base Integration: via Passive App (pRMT) + +[RADAR-base Polar Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/polar) + +![](./img/supported-devices-e4-1-500x286.png) + +## Empatica E4 + +**Empatica E4** + +Wrist worn + +Raw acceleration\ +Heart rate (PPG)\ +Blood volume pulse (PPG)\ +Electro Dermal Activity\ +Temperature + +RADAR-base Integration: via Passive App (pRMT) + +[RADAR-base E4 Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/empatica) + +![](./img/supported-devices-screenshot-from-2024-03-05-18-51-54.png) + +## IoT Sensors + +Static environments + +Supports various IoT sensing devices including support for common I/O protocols such as GPIO, I2C and Serial. It currently supports temperature, humidity, motion, light, air quality, and gas sensors. Easy to extend and support new sensor types. + +RADAR-base Integration: via RADAR-IoT Module + +[RADAR-base IoT Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/sensors/commons/iot/sensor) + +![](./img/supported-devices-faros-500x286.png) + +## Faros + +Chest/pocket + +Raw acceleration\ +Heart rate (ECG raw waveform)\ +Temperature + +RADAR-base Integration: via Passive App (pRMT)\ +Notice: Deprecated Device + +[RADAR-base Faros Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/bittium) + +![](./img/supported-devices-biovotion-500x286.png) + +## Biovotion + +Upperarm + +Raw acceleration\ +Heart rate (PPG)\ +Heart rate variability (PPG)\ +Blood volume pulse (PPG)\ +Electro Dermal Activity (GSR)\ +Temperature\ +Respiration rate\ +Oxygen saturation + +RADAR-base Integration: via Passive App (pRMT)\ +Notice: Deprecated Device + +[RADAR-base Biovotion Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/biovotion) + +![](./img/supported-devices-pebble-500x286.png) + +## Pebble 2 + +Wrist worn + +Raw acceleration\ +Heart rate (PPG) + +RADAR-base Integration: via Passive App (pRMT)\ +Notice: Deprecated Device + +[RADAR-base Pebble Schemas](https://github.com/RADAR-base/RADAR-Schemas/tree/master/commons/passive/pebble) + +--- + +_This page was copied from [Supported devices](https://radar-base.org/docs/supported-devices/) on the RADAR-base website (3 September 2026). If you change it here, change it there too._ diff --git a/content/participant/active-app-user-guide.md b/content/participant/active-app-user-guide.md new file mode 100644 index 0000000..9930aeb --- /dev/null +++ b/content/participant/active-app-user-guide.md @@ -0,0 +1,23 @@ +--- +title: "Active App User Guide documents" +sidebar_label: "Active app user guide" +sidebar_position: 2 +description: "Graphical user guide for participants: the active (questionnaire) app." +--- + +Graphical user guide document for the RADAR-base active (questionnaire) app. + +
+ +
+ +
+ +[RADAR-Base Active App User Guide](https://www.canva.com/design/DAG6qE9ng7M/Ixgi5-RGB2fglMDtyixb7Q/view?utm_content=DAG6qE9ng7M&utm_campaign=designshare&utm_medium=embeds&utm_source=link) +by Wally — opens in Canva, where the guide can be read full screen or downloaded. + +
diff --git a/content/participant/img/user-guides-image-1.png b/content/participant/img/user-guides-image-1.png new file mode 100644 index 0000000..23dc3f5 Binary files /dev/null and b/content/participant/img/user-guides-image-1.png differ diff --git a/content/participant/img/user-guides-image.png b/content/participant/img/user-guides-image.png new file mode 100644 index 0000000..89cf8b2 Binary files /dev/null and b/content/participant/img/user-guides-image.png differ diff --git a/content/participant/intro.md b/content/participant/intro.md new file mode 100644 index 0000000..20726c1 --- /dev/null +++ b/content/participant/intro.md @@ -0,0 +1,30 @@ +--- +title: Participant documentation +slug: / +sidebar_position: 1 +description: Graphical user guides written for the people taking part in a RADAR-base study. +--- + +# Participant documentation + +Graphical user guide documents for RADAR-base, written for the people taking part in a study. +Each guide is a Canva design, embedded here and readable full screen or downloadable from +Canva itself. + +[![Cover of the active app user guide](./img/user-guides-image-1.png)](./active-app-user-guide.md) + +**[Active app user guide](./active-app-user-guide.md)** — getting started with the active +(questionnaire) app. + +[![Cover of the wearable user guide](./img/user-guides-image.png)](./wearable-user-guides.md) + +**[Wearable user guide](./wearable-user-guides.md)** — getting started with the wearable +device. + +For the apps and devices themselves, see [Client documentation](/client/). + +:::note Copied from the RADAR-base website +These guides were copied from +[User guide documents](https://radar-base.org/docs/user-guide-documents/) on the RADAR-base +website (3 September 2026). If you change them here, change them there too. +::: diff --git a/content/participant/wearable-user-guides.md b/content/participant/wearable-user-guides.md new file mode 100644 index 0000000..6a3bde4 --- /dev/null +++ b/content/participant/wearable-user-guides.md @@ -0,0 +1,23 @@ +--- +title: "Wearable User Guide documents" +sidebar_label: "Wearable user guide" +sidebar_position: 3 +description: "Graphical user guide for participants: the wearable device." +--- + +Graphical user guide document for the wearable devices used in RADAR-base studies. + +
+ +
+ +
+ +[Wearable User Guide](https://www.canva.com/design/DAHPSf_Vzp0/4eEDMaYDETeudTd6T8Ydsw/view) +— opens in Canva, where the guide can be read full screen or downloaded. + +
diff --git a/content/platform/concepts-and-components.md b/content/platform/concepts-and-components.md new file mode 100644 index 0000000..f2e8953 --- /dev/null +++ b/content/platform/concepts-and-components.md @@ -0,0 +1,102 @@ +--- +title: "Concepts and components of RADAR-base" +sidebar_position: 2 +sidebar_label: "Concepts and Components" +description: "How the platform fits together: its architecture, the streaming core, and the role of each component." +--- + +## Insight of RADAR-base platform + +RADAR-Base is an open source data collection and management platform for remote assessment of diseases using various wearable devices and mobile application technologies. + +### Concepts behind the RADAR-base platform architecture + +The RADAR-base platform architecture was built with extensibility, flexibility and scalability in mind. Hence, the platform is designed using **plugin-based architecture** which allows various data ingestion, validation, authorization and access methods can be used. The architecture of RADAR-base makes great use of **[Apache Kafka](https://kafka.apache.org/)** and the **[Confluent platform](https://www.confluent.io/)**, a state of the art technology for distributed real time streaming. **Apache Kafka** is a novel appropriate for building real-time streaming/transforming data pipelines that reliably move data between systems at scale. + +RADAR-base is built on top of the concept of **Kafka Connectors** introduced by the Confluent platform. Kafka Connectors are components built using Kafka connect APIs, an interface that simplifies and automates the integration of a new data sources or data consumers to a Kafka cluster. Kafka connectors can be categorized into **Source connectors** (to ingest data into Kafka cluster) and **Sink connectors** (to consume data from Kafka cluster). The diagram below depicts the high level architecture of data collection and management of RADAR-base platform. + +### High-level Architecture + +![](./img/concepts-and-components-selection-038-1024x462.png) + +## Data Ingestion + +### Device Connector Plugin Middle-ware + +RADAR-base platform provides a [middle-ware](https://github.com/RADAR-CNS/RADAR-Commons-Android) that **can be extended to integrate various data-sources**. Currently, platform provides stable support for Android OS and recently started investigating to extend the support for iOS. It provides an abstract API layer, that could be easily extended to send device specific data. This abstract layer can handle authorization, encode data using Avro schemas, send data to Kafka topics using HTTPS requests. Extending this component eliminates the difficulties in implementing security, Kafka related functionalities for each devices and encapsulates platform specific implementations. + +### Device Connector Plugins + +A device-specific “**device connector plugin app**” can be easily implemented for every device with an Android SDK and could stream data in real-time. By extending the API layer provided by the device connector plugin provided above, sensor data collected from each device and streamed to RADAR-base back-end. Every record of sensor data is converted to Kafka messages and published to specific Kafka topics. + +These are plug-in based applications that could be easily added or removed from the final [passive data collection app](https://github.com/RADAR-base/radar-prmt-android). Some of the plugin applications that are already implement are given below: + +- [Pebble](https://github.com/RADAR-CNS/RADAR-Android-Pebble) +- [Empatica E4](https://github.com/RADAR-CNS/RADAR-Android-Empatica) +- [Faros](https://github.com/RADAR-base/radar-android-faros) +- [Biovotion](https://github.com/RADAR-CNS/RADAR-Android-Biovotion) +- [Android mobile phone sensors](https://github.com/RADAR-CNS/RADAR-Android-Phone) + +### REST Source Connector + +For the devices, which do not have an SDK to send data through Bluetooth or directly send data to their data warehouses and provide APIs to access data from their services, a [REST source connector](https://github.com/RADAR-base/RADAR-REST-Connector) is provided. It receives data from provided APIs and sends them as Kafka messages in relevant Avro formats. It is a Kafka source connector that extends the kafka-connect API. + +## Data Processing + +### Kafka cluster + +[Apache Kafka](https://kafka.apache.org/) is a distributed **publish-subscribe** based message queuing system. A **publisher** can produce messages to a specific topic. A **subscriber** who listens to a topic can consume messages published to that topic. Kafka keeps track of each message using an offset. Kafka also supports distributed partitions as an immutable commit log of messages offsets with the guarantee of emitted order preservation. A **Kafka cluster** can contain multiple Kafka servers and need to be coordinated by **Zookeeper,** which is a distributed resource coordinator. Kafka broker setup with integrated with Zookeeper, schema-registry, and REST-proxy are supported out of the box by the Confluent platform. + +### Schema Registry + +Schema registry is a component provided by the Confluent platform, to manage [Avro schemas](https://avro.apache.org/). It offers functionalities for storing a versioned history of schemas, with multiple compatibility settings and managing the evolution of schemas. It provides a RESTful interface to store and retrieve schemas. + +### Kafka Rest Proxy + +The **Kafka-REST-proxy** is a RESTFul Kafka producer provided by the Confluent platform. It can produce Kafka messages with/without corresponding Avro schemas and publish them using HTTP requests. It provides the interoperability to support client applications with various programming languages and eliminates Kafka specific implementation complexities. Multiple deployments of Kafka-REST-proxy allow easy load balancing on larger-scale deployment of the middle-ware. + +### Aggregating Streams and Monitor + +[RADAR-backend](https://github.com/RADAR-CNS/RADAR-Backend) implements [Kafka Streams](https://kafka.apache.org/documentation/streams/), to **compute aggregated values** of published data based on various time windows and **to monitor data quality and compliance**. The aggregated values are stored on separate topics and consumed by a sink-connector. The monitors are used to validate data quality and compliance and to provide email alerts for early interventions. For example, a battery level monitor is provided, which alerts the user/researcher by sending an email notification when battery level is found low according to given criteria. + +**Note:** This component runs multiple Kafka Streams for real-time computations which uses high computing power. If real-time monitoring and visualization are not compulsory requirements we advise to turn these serves off. + +## Data Storage + +### HDFS Sink Connector + +To support offline retrospective analysis, a [HDFS Sink connector](https://github.com/RADAR-CNS/RADAR-HDFS-Sink-Connector) is provided, which is called the **“cold storage”**. It consumes all the data from Kafka topics and writes them to HDFS filesystem. The HDFS sink connector is an extension of Kafka-hdfs-connector. It can be configured to consume various topics and store them in different locations in HDFS. + +### MongoDB Sink Connector + +A [MongoDB Sick Connector](https://github.com/RADAR-CNS/RADAR-MongoDB-Sink-Connector) is created to provide near real-time overview of the data. It consumes aggregated-data computed and stored by Kafka-Streams mentioned in [RADAR-backend,](https://github.com/RADAR-CNS/RADAR-Backend) and writes them as MongoDB documents. It is called as the **“hot storage”** of the RADAR-base platform. These near real-time data can be accessed either directly via querying the database or querying using integrated RESTful API. + +## Data Extraction and Visualization + +### REST-API Service + +[RADAR-REST-API](https://github.com/RADAR-CNS/RADAR-RestApi) component of RADAR-base, provides interfaces to access the aggregated data stored in MongoDB. It is also integrated with the study management system of the platform and handles authorization. The REST-API component include APIs to access metadata of the studies, participants and data sources in addition providing access to aggregated data. + +### Dashboard + +The [dashboard](https://github.com/RADAR-CNS/RADAR-Dashboard) component provides user interfaces to visualize near real-time sensor data and the platform status. It uses the [REST-API](https://github.com/RADAR-CNS/RADAR-RestApi) to access the data stored in the platform. Various visualization widgets are implemented to visualize sensor data including charts, graphs etc. + +### HDFS Data Extractor + +Data streamed to HDFS using the [RADAR HDFS sink connector](https://github.com/RADAR-CNS/RADAR-HDFS-Sink-Connector) is stored as files based on sensor(topic) only. This [utility package](https://github.com/RADAR-CNS/Restructure-HDFS-topic) can transform that output to a local directory structure as follows: **projectId/userId/topic/date\_hour.csv**. Currently, it can export avro data into avro, JSON and CSV formats. + +## Study Management and Security + +### Management Portal + +RADAR-base provides a **centralized study management system** called [Management Portal](https://github.com/RADAR-base/ManagementPortal) to manage multiple **studies, users and their roles** to guarantee security and privacy. This web application is the main user interface for planning and managing multiple studies, enrolling participants and managing the association of participants with corresponding data sources (devices and apps). This system controls the **authentication and authorization of data** operations and **de-Identification** of all the data identifiers. + +### Gateway + +[RADAR-Gateway](https://github.com/RADAR-CNS/RADAR-Gateway) is a component which behaves as an entry-point to RADAR-base platform back-end. It **validates the user identity and access**, (i.e. authentication and authorization), schematic validation, load-balancing of the Kafka-REST-proxy etc. All of the data sent to the RADAR-base platform is verified using the RADAR-gateway before the data is published on Kafka cluster. + +Read the step-by-step guidelines on [How to Install RADAR-base](https://radar-base.org/docs/installation/). + +--- + +_This page was copied from [Concepts and components of RADAR-base](https://radar-base.org/docs/concepts-and-components-of-radar-base/) on the RADAR-base website (3 September 2026). If you change it here, change it there too._ diff --git a/content/platform/faq.md b/content/platform/faq.md index 9295b25..604f4b9 100644 --- a/content/platform/faq.md +++ b/content/platform/faq.md @@ -1,6 +1,6 @@ --- title: FAQ and common issues -sidebar_position: 2 +sidebar_position: 3 --- # FAQ and common issues diff --git a/content/platform/img/concepts-and-components-selection-038-1024x462.png b/content/platform/img/concepts-and-components-selection-038-1024x462.png new file mode 100644 index 0000000..04fe7d5 Binary files /dev/null and b/content/platform/img/concepts-and-components-selection-038-1024x462.png differ diff --git a/content/platform/intro.md b/content/platform/intro.md index 798c577..586c602 100644 --- a/content/platform/intro.md +++ b/content/platform/intro.md @@ -27,30 +27,26 @@ sections are thinner than they will be. If something is missing or wrong, see th - **Components** — one section per repository, each with its own version picker. Pages under a released version match that release; the version labelled *Next* tracks the component's default branch. -- **Client** and **Participant** — the apps, devices and participant-facing guides, - maintained on the [RADAR-base website](https://radar-base.org/docs/) and linked from the - navigation. See [Background reading](#background-reading) below. +- **[Client](/client/)** and **[Participant](/participant/)** — the apps, devices and + participant-facing guides. These pages were copied from the RADAR-base website so they can + be read and searched alongside everything else here. - **[FAQ and common issues](./faq.md)** — where to ask questions, and the problems that come up most often. ## Background reading -Higher-level material about the platform is published on the RADAR-base website rather than -in a repository: +[Concepts and components of RADAR-base](./concepts-and-components.md) is the place to start on +how the platform fits together: the plugin-based architecture, the Kafka streaming core, and +the role each component plays in it. -- [Concepts and components of RADAR-base](https://radar-base.org/docs/concepts-and-components-of-radar-base/) - — how the platform fits together: the plugin-based architecture, the Kafka streaming core, - and the role each component plays in it. - -For running a study, the **Client** menu covers the -[questionnaire (aRMT)](https://radar-base.org/docs/questionnaire-app/) and -[passive (pRMT)](https://radar-base.org/docs/prmt-app/) apps, the -[phone sensors](https://radar-base.org/docs/4048-2/) and -[devices](https://radar-base.org/docs/supported-devices/) they collect from, and -[authorising third-party wearable accounts](https://radar-base.org/docs/radar-rest-source-auth/). -The **Participant** menu has the -[user guide documents](https://radar-base.org/docs/user-guide-documents/) written for study -participants. +For running a study, the **Client** section covers the +[questionnaire (aRMT)](/client/questionnaire-app) and [passive (pRMT)](/client/passive-app) +apps, the [phone sensors](/client/phone-data-sensors) and +[devices](/client/supported-devices) they collect from, and +[authorising third-party wearable accounts](/client/rest-source-auth). The **Participant** +section has the guides written for study participants: the +[active app guide](/participant/active-app-user-guide) and the +[wearable guide](/participant/wearable-user-guides). ## Where to start diff --git a/docusaurus.config.js b/docusaurus.config.js index 65955ff..bd1fe42 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -2,7 +2,7 @@ const fs = require('node:fs'); const path = require('node:path'); const {themes} = require('prism-react-renderer'); -const {externalDocSections, platformDocs} = require('./src/data/externalDocs'); +const {guideSections, platformGuides} = require('./src/data/guides'); /** * One published component, as written to .generated/repos.json by scripts/fetch-docs.mjs. @@ -64,6 +64,25 @@ const docsPlugins = repos.map((repo) => [ }, ]); +/** + * Documentation written in this repository that is not about one component: the client and + * participant guides, copied from radar-base.org. Each is a docs section of its own so it + * gets its own sidebar and route, the same as the platform section. + */ +const guidePlugins = [ + ['client', 'Client'], + ['participant', 'Participant'], +].map(([id, name]) => [ + '@docusaurus/plugin-content-docs', + { + id, + path: `content/${id}`, + routeBasePath: `/${id}`, + sidebarPath: require.resolve(`./sidebars${name}.js`), + editUrl: 'https://github.com/RADAR-base/radar-base-docs/edit/main/', + }, +]); + const searchPlugin = (() => { try { require.resolve('@easyops-cn/docusaurus-search-local'); @@ -76,8 +95,18 @@ const searchPlugin = (() => { { hashed: true, indexBlog: false, - docsDir: ['content/platform', ...repos.map((repo) => `docs/${repo.id}`)], - docsRouteBasePath: ['/platform', ...repos.map((repo) => repo.route)], + docsDir: [ + 'content/platform', + 'content/client', + 'content/participant', + ...repos.map((repo) => `docs/${repo.id}`), + ], + docsRouteBasePath: [ + '/platform', + '/client', + '/participant', + ...repos.map((repo) => repo.route), + ], }, ], ]; @@ -130,7 +159,7 @@ const config = { ], ], - plugins: [...docsPlugins, ...searchPlugin], + plugins: [...docsPlugins, ...guidePlugins, ...searchPlugin], themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ @@ -149,14 +178,17 @@ const config = { position: 'left', items: repos.map((repo) => ({to: `${repo.route}/`, label: repo.label})), }, - // Client and participant documentation is published on radar-base.org, not in a - // repository, so these entries link out. See src/data/externalDocs.js. - ...externalDocSections.map((section) => ({ - type: 'dropdown', - label: section.title.replace(' documentation', ''), - position: 'left', - items: section.docs.map((doc) => ({href: doc.href, label: doc.label})), - })), + // The client and participant guides. See src/data/guides.js. + ...guideSections.map((section) => + section.pages.length > 1 + ? { + type: 'dropdown', + label: section.navLabel, + position: 'left', + items: section.pages.map((page) => ({to: page.to, label: page.label})), + } + : {to: section.route, label: section.navLabel, position: 'left'}, + ), {to: '/platform/faq', label: 'FAQ', position: 'left'}, // Shows the version picker for whichever component the reader is in. {type: 'custom-activeDocsVersionDropdown', position: 'right'}, @@ -174,12 +206,12 @@ const config = { ], }, { - title: 'Clients and participants', + title: 'Guides', items: [ - ...externalDocSections.flatMap((section) => - section.docs.map((doc) => ({label: doc.label, href: doc.href})), + ...guideSections.flatMap((section) => + section.pages.map((page) => ({label: page.label, to: page.to})), ), - ...platformDocs.map((doc) => ({label: doc.label, href: doc.href})), + ...platformGuides.map((page) => ({label: page.label, to: page.to})), ], }, { diff --git a/sidebars.js b/sidebars.js index 2ad970c..aae245a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1,19 +1,7 @@ -const {platformDocs} = require('./src/data/externalDocs'); - /** * Sidebar for the platform-wide documentation in content/platform. * Each component's sidebar is generated from its own repository — see scripts/fetch-docs.mjs. */ module.exports = { - platform: [ - {type: 'autogenerated', dirName: '.'}, - // Higher-level background on the platform is maintained on radar-base.org; it belongs - // in this section even though the pages are not part of this site. - { - type: 'category', - label: 'Concepts and Components', - collapsed: false, - items: platformDocs.map((doc) => ({type: 'link', label: doc.label, href: doc.href})), - }, - ], + platform: [{type: 'autogenerated', dirName: '.'}], }; diff --git a/sidebarsClient.js b/sidebarsClient.js new file mode 100644 index 0000000..7ccd558 --- /dev/null +++ b/sidebarsClient.js @@ -0,0 +1,7 @@ +/** + * Sidebar for the client documentation in content/client — the apps and devices a study + * runs on. Ordering comes from each page's `sidebar_position`. + */ +module.exports = { + client: [{type: 'autogenerated', dirName: '.'}], +}; diff --git a/sidebarsParticipant.js b/sidebarsParticipant.js new file mode 100644 index 0000000..c7808ba --- /dev/null +++ b/sidebarsParticipant.js @@ -0,0 +1,7 @@ +/** + * Sidebar for the participant documentation in content/participant — material written for + * the people taking part in a study. + */ +module.exports = { + participant: [{type: 'autogenerated', dirName: '.'}], +}; diff --git a/src/css/custom.css b/src/css/custom.css index 3c8beb8..cbd3fcd 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -155,12 +155,60 @@ color: var(--ifm-color-emphasis-700); } -/* Cards that leave the site read as links, not as another documentation section. */ -.componentCard--external { - border-style: dashed; +/** + * The client and participant pages were copied from a site whose layout sized their images + * for it: portrait phone screenshots, and guide covers shown as thumbnails. Cap them here so + * a page does not turn into a column of full-width images. Component documentation is left + * alone — those pages size their own images. + */ +.plugin-id-client .markdown img, +.plugin-id-participant .markdown img { + max-height: 26rem; + width: auto; + border-radius: var(--ifm-global-radius); +} + +/* Cover art for a downloadable guide is a thumbnail, not an illustration. */ +.plugin-id-participant .markdown a > img { + max-height: 18rem; +} + +/** + * The participant guides are Canva designs, embedded so they can be read without leaving + * the page. The source markup sized each frame with inline styles and a padding-top ratio + * hack; a class keeps the markdown readable and the two guides identical. Both designs are + * A4 portrait, which is what the ratio below describes. + */ +.canvaEmbed { + position: relative; + width: 100%; + max-width: 44rem; + aspect-ratio: 1 / 1.4142; + margin: 1.6rem 0 0.9rem; + overflow: hidden; + border-radius: 8px; + box-shadow: 0 2px 8px 0 rgba(63, 69, 81, 0.16); + /* Visible while the embed loads, and if a privacy extension blocks it outright. */ + background: var(--ifm-color-emphasis-200); +} + +.canvaEmbed iframe { + position: absolute; + inset: 0; + width: 100%; + height: 100%; + margin: 0; + padding: 0; + border: none; +} + +/* The embed is not always available, and the design reads better full screen on a phone. */ +.embedCaption { + max-width: 44rem; + font-size: 0.9rem; + color: var(--ifm-color-emphasis-700); } -.componentCard__external { - font-size: 0.85em; - opacity: 0.7; +.embedCaption p { + margin-bottom: 0; } diff --git a/src/data/externalDocs.js b/src/data/externalDocs.js deleted file mode 100644 index c4dc9e2..0000000 --- a/src/data/externalDocs.js +++ /dev/null @@ -1,103 +0,0 @@ -/** - * Documentation that lives on radar-base.org rather than in a component repository. - * - * Everything under **Components** is fetched from the repository that owns it (see - * repos.yml). The pages below are not in any repository: they describe the platform from - * the point of view of the people running a study and the people taking part in one, and - * they are maintained on the RADAR-base website. Linking to them keeps them in the - * navigation without this site holding a stale copy. - * - * Both the navbar (docusaurus.config.js) and the home page (src/pages/index.js) are built - * from this file, so a page added here appears in both. - * - * @typedef {object} ExternalDoc - * @property {string} label Link text, matching the page's own title. - * @property {string} href Absolute URL on radar-base.org. - * @property {string} description One line, summarising the page as it currently reads. - * - * @typedef {object} ExternalDocSection - * @property {string} id Used for the home-page anchor, e.g. "client-documentation". - * @property {string} title Section heading, and the navbar label. - * @property {string} blurb Who the section is for, shown under the heading. - * @property {ExternalDoc[]} docs - */ - -/** Where the linked pages are published; shown on each card so the link is not a surprise. */ -const EXTERNAL_HOST = 'radar-base.org'; - -/** @type {ExternalDocSection} */ -const clientDocs = { - id: 'client-documentation', - title: 'Client documentation', - blurb: - 'The apps and devices a study runs on: what they collect, which hardware is supported, ' + - 'and how participants are connected to third-party wearable accounts.', - docs: [ - { - label: 'RADAR-Rest-Source-Auth', - href: 'https://radar-base.org/docs/radar-rest-source-auth/', - description: - 'Authorising RADAR-base to collect from third-party wearable APIs — Oura, Fitbit and Garmin — through the REST authorizer.', - }, - { - label: 'Questionnaire app (aRMT)', - href: 'https://radar-base.org/docs/questionnaire-app/', - description: - 'The configurable questionnaire app for active tasks: scheduling, notifications and questionnaire definitions, on Android and iOS.', - }, - { - label: 'Passive app (pRMT)', - href: 'https://radar-base.org/docs/prmt-app/', - description: - 'The passive app that collects background sensor data from the phone and from paired wearables through plugins.', - }, - { - label: 'Phone data sensors', - href: 'https://radar-base.org/docs/4048-2/', - description: - 'What each phone sensor the passive app supports actually records, and where its schema is defined.', - }, - { - label: 'Supported devices', - href: 'https://radar-base.org/docs/supported-devices/', - description: - 'The wearables and devices integrated into the platform, and the data types each one contributes.', - }, - ], -}; - -/** @type {ExternalDocSection} */ -const participantDocs = { - id: 'participant-documentation', - title: 'Participant documentation', - blurb: - 'Material written for the people taking part in a study, to hand out or adapt for your own.', - docs: [ - { - label: 'User guide documents', - href: 'https://radar-base.org/docs/user-guide-documents/', - description: - 'Graphical user guides for participants: getting started with the wearable, and with the active (questionnaire) app.', - }, - ], -}; - -/** - * Platform-level background that is not specific to any one component. Shown in the - * Platform section rather than as a section of its own. - * - * @type {ExternalDoc[]} - */ -const platformDocs = [ - { - label: 'Concepts and components of RADAR-base', - href: 'https://radar-base.org/docs/concepts-and-components-of-radar-base/', - description: - 'How the platform fits together: the plugin-based architecture, the Kafka streaming core, and the role each component plays in it.', - }, -]; - -/** The sections rendered as their own home-page block and navbar entry, in order. */ -const externalDocSections = [clientDocs, participantDocs]; - -module.exports = {EXTERNAL_HOST, clientDocs, participantDocs, platformDocs, externalDocSections}; diff --git a/src/data/guides.js b/src/data/guides.js new file mode 100644 index 0000000..82d2026 --- /dev/null +++ b/src/data/guides.js @@ -0,0 +1,107 @@ +/** + * The guide sections that are written here rather than fetched from a component repository. + * + * Everything under **Components** comes from the repository that owns it (see repos.yml). + * These two sections do not belong to any one component: they describe the platform from the + * point of view of the people running a study and the people taking part in one. Their pages + * were copied from radar-base.org into content/client and content/participant, and each page + * links back to the page it came from. + * + * The navbar (docusaurus.config.js) and the home page (src/pages/index.js) are both built + * from this file, so a page added to a section appears in both. + * + * @typedef {object} Guide + * @property {string} label Link text. + * @property {string} to Route on this site. + * @property {string} description One line, summarising the page. + * + * @typedef {object} GuideSection + * @property {string} id Home-page anchor, e.g. "client-documentation". + * @property {string} title Section heading on the home page. + * @property {string} navLabel Navbar label. + * @property {string} route Section landing page. + * @property {string} blurb Who the section is for. + * @property {Guide[]} pages + */ + +/** @type {GuideSection} */ +const clientGuides = { + id: 'client-documentation', + title: 'Client documentation', + navLabel: 'Client', + route: '/client/', + blurb: + 'The apps and devices a study runs on: what they collect, which hardware is supported, ' + + 'and how participants are connected to third-party wearable accounts.', + pages: [ + { + label: 'RADAR-Rest-Source-Auth', + to: '/client/rest-source-auth', + description: + 'Authorising RADAR-base to collect from third-party wearable APIs — Oura, Fitbit and Garmin — through the REST authorizer.', + }, + { + label: 'Questionnaire app (aRMT)', + to: '/client/questionnaire-app', + description: + 'The configurable questionnaire app for active tasks: scheduling, notifications and questionnaire definitions, on Android and iOS.', + }, + { + label: 'Passive app (pRMT)', + to: '/client/passive-app', + description: + 'The passive app that collects background sensor data from the phone and from paired wearables through plugins.', + }, + { + label: 'Phone data sensors', + to: '/client/phone-data-sensors', + description: + 'What each phone sensor the passive app supports actually records, and where its schema is defined.', + }, + { + label: 'Supported devices', + to: '/client/supported-devices', + description: + 'The wearables and devices integrated into the platform, and the data types each one contributes.', + }, + ], +}; + +/** @type {GuideSection} */ +const participantGuides = { + id: 'participant-documentation', + title: 'Participant documentation', + navLabel: 'Participant', + route: '/participant/', + blurb: + 'Material written for the people taking part in a study, to hand out or adapt for your own.', + pages: [ + { + label: 'Active app user guide', + to: '/participant/active-app-user-guide', + description: + 'Graphical user guide for participants: getting started with the active (questionnaire) app.', + }, + { + label: 'Wearable user guide', + to: '/participant/wearable-user-guides', + description: + 'Graphical user guide for participants: getting started with the wearable device.', + }, + ], +}; + +/** Platform-level background, shown in the Platform section rather than one of its own. */ +const platformGuides = [ + { + label: 'Concepts and components of RADAR-base', + to: '/platform/concepts-and-components', + description: + 'How the platform fits together: the plugin-based architecture, the Kafka streaming core, and the role each component plays in it.', + }, +]; + +/** The sections that get their own home-page block and navbar entry, in order. */ +const guideSections = [clientGuides, participantGuides]; + +module.exports = {clientGuides, participantGuides, platformGuides, guideSections}; diff --git a/src/pages/index.js b/src/pages/index.js index fdab290..dbedfbd 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -3,7 +3,8 @@ import Link from '@docusaurus/Link'; import useBaseUrl from '@docusaurus/useBaseUrl'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import Layout from '@theme/Layout'; -import {EXTERNAL_HOST, externalDocSections} from '../data/externalDocs'; + +import {guideSections} from '../data/guides'; /** * The component list is whatever the last documentation fetch produced, so a repository @@ -26,27 +27,21 @@ function ComponentCard({repo}) { } /** - * Client and participant documentation lives on radar-base.org, so these cards leave the - * site. The host is on the card, and the arrow marks the link, so that is not a surprise. + * A page in one of the guide sections. These read like the component cards, because they + * are the same kind of thing to a reader: a piece of documentation this site publishes. */ -function ExternalDocCard({doc}) { +function GuideCard({page}) { return (
  • - -

    - {doc.label} - -

    -

    {doc.description}

    -
    - {EXTERNAL_HOST} -
    + +

    {page.label}

    +

    {page.description}

    • ); } -function ExternalDocSection({section}) { +function GuideSection({section}) { return ( <>

    @@ -54,8 +49,8 @@ function ExternalDocSection({section}) {

    {section.blurb}

    @@ -113,8 +108,8 @@ export default function Home() { )} - {externalDocSections.map((section) => ( - + {guideSections.map((section) => ( + ))}

    Questions and common issues