Merge branch 'main' of https://github.com/brown-ccv/honeycomb

.eslintrc.js

@@ -25,6 +25,13 @@ module.exports = {
     react: {
       version: "detect",
     },
+    jsdoc: {
+      tagNamePreference: {
+        typedef: {
+          definedInFiles: ["src/lib/typedef.js"],
+        },
+      },
+    },
     "import/resolver": {
       node: {
         extensions: [".js", ".jsx"],

package.json

@@ -23,7 +23,7 @@
     "@jspsych/plugin-initialize-camera": "^1.0.1",
     "@jspsych/plugin-instructions": "^1.1.3",
     "@jspsych/plugin-preload": "^1.1.2",
-    "@jspsych/plugin-survey": "^0.2.2",
+    "@jspsych/plugin-survey": "^1.0.1",
     "bootstrap": "^5.2.0-beta1",
     "electron-log": "^5.0.0",
     "electron-squirrel-startup": "^1.0.0",
@@ -53,7 +53,7 @@
     "cross-env": "^7.0.3",
     "cz-conventional-changelog": "^3.2.0",
     "dotenv-cli": "^7.0.0",
-    "electron": "^30.0.1",
+    "electron": "^31.0.2",
     "eslint": "^8.54.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-import": "^2.29.0",

public/electron/main.js

@@ -8,6 +8,8 @@ const { app, BrowserWindow, ipcMain, dialog } = require("electron");
 const log = require("electron-log");
 const _ = require("lodash");
 
+const { MockBinding } = require("@serialport/binding-mock");
+const { SerialPortStream } = require("@serialport/stream");
 const { getPort, sendToPort } = require("./serialPort");
 
 // TODO @brown-ccv #460: Add serialport's MockBinding for the "Continue Anyway": https://serialport.io/docs/guide-testing
@@ -30,7 +32,6 @@ const GIT_VERSION = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../versi
 const ELECTRON_START_URL = process.env.ELECTRON_START_URL;
 
 let CONFIG; // Honeycomb configuration object
-let CONTINUE_ANYWAY; // Whether to continue the experiment with no hardware connected (option is only available in dev mode)
 
 let TEMP_FILE; // Path to the temporary output file
 let OUT_PATH; // Path to the final output folder (on the Desktop)
@@ -364,7 +365,6 @@ async function setUpPort() {
             app.exit();
           } else {
             // User selected "Continue Anyway", trigger port is not connected
-            CONTINUE_ANYWAY = true;
             TRIGGER_PORT = undefined;
           }
         });
@@ -381,10 +381,7 @@ async function setUpPort() {
  * @param code The code to send via USB
  */
 function handleEventSend(code) {
-  log.info(`Sending USB event ${code} to port ${TRIGGER_PORT}`);
-
-  // Early return when running in development (no trigger port is expected)
-  if (CONTINUE_ANYWAY) return;
+  log.info(`Sending USB event: ${code}`);
 
   if (TRIGGER_PORT !== undefined) {
     sendToPort(TRIGGER_PORT, code);
@@ -415,8 +412,16 @@ function handleEventSend(code) {
         setUpPort().then(() => handleEventSend(code));
         break;
       case 2:
-        // User selects "Continue Anyway", we must be in dev mode
-        CONTINUE_ANYWAY = true;
+        // set-up mockbinding and open port for communication if continue anyway is clicked
+        MockBinding.createPort("/dev/ROBOT", {
+          echo: true,
+          record: true,
+        });
+        TRIGGER_PORT = new SerialPortStream({
+          binding: MockBinding,
+          path: "/dev/ROBOT",
+          baudRate: 14400,
+        });
         break;
     }
   }

src/App/components/Login.jsx

@@ -1,5 +1,5 @@
 import PropTypes from "prop-types";
-import React, { useEffect } from "react";
+import React from "react";
 import { Button, Form } from "react-bootstrap";
 
 export default function Login({
@@ -11,23 +11,31 @@ export default function Login({
   // State variables for login screen
   const [participantID, setParticipantID] = React.useState(initialParticipantID);
   const [studyID, setStudyID] = React.useState(initialStudyID);
+
+  // State variable for handling errors
   const [isError, setIsError] = React.useState(false);
 
+  // State variable for handling loading states
+  const [isLoading, setIsLoading] = React.useState(false);
+
   // Update local participantID if it changes upstream
-  useEffect(() => {
+  React.useEffect(() => {
     setParticipantID(initialParticipantID);
   }, [initialParticipantID]);
 
   // Update local studyID if it changes upstream
-  useEffect(() => {
+  React.useEffect(() => {
     setStudyID(initialStudyID);
   }, [initialStudyID]);
 
   // Function used to validate and log in participant
   function handleSubmit(e) {
     e.preventDefault();
+    setIsLoading(true);
+
     // Logs user in if a valid participant/study id combination is given
     validationFunction(studyID, participantID).then((isValid) => {
+      setIsLoading(false);
       setIsError(!isValid);
       if (isValid) handleLogin(studyID, participantID);
     });
@@ -41,32 +49,28 @@ export default function Login({
             <Form.Label>Participant ID</Form.Label>
             <Form.Control
               autoFocus
-              type="participantID"
+              name="participantID"
+              required={true}
               value={participantID}
               onChange={(e) => setParticipantID(e.target.value)}
             />
           </Form.Group>
           <Form.Group className="width-100" size="lg" controlId="studyID">
             <Form.Label>Study ID</Form.Label>
             <Form.Control
-              type="studyID"
+              name="studyID"
+              required={true}
               value={studyID}
               onChange={(e) => setStudyID(e.target.value)}
             />
           </Form.Group>
-          <Button
-            style={{ width: "100%" }}
-            block
-            size="lg"
-            type="submit"
-            disabled={studyID.length === 0 || participantID.length === 0}
-          >
-            Log In
+          <Button style={{ width: "100%" }} block size="lg" type="submit">
+            {isLoading ? "Submitting..." : "Log In"}
           </Button>
         </Form>
         {isError ? (
           <div className="alert alert-danger" role="alert">
-            No matching experiment found for this participant and study
+            Unable to begin the study. Is your login information correct?
           </div>
         ) : null}
       </div>

src/experiment/honeycomb.js

@@ -3,6 +3,7 @@ import { buildHoneycombProcedure } from "./procedures/honeycombProcedure";
 import { buildStartProcedure } from "./procedures/startProcedure";
 
 import { buildDebriefTrial, instructionsTrial, preloadTrial } from "./trials/honeycombTrials";
+import { buildCountdownTrial } from "./trials/countdown";
 
 /**
  * ! This file should not be edited! Instead, create a new file with the name of your task
@@ -31,8 +32,8 @@ export const honeycombOptions = {
  * Take a look at how the code here compares to the jsPsych documentation!
  * See the jsPsych documentation for more: https://www.jspsych.org/7.3/tutorials/rt-task/
  *
- * @param {Object} jsPsych The jsPsych instance being used to run the task
- * @returns {Object} A jsPsych timeline object
+ * @param {JsPsych} jsPsych The jsPsych instance being used to run the task
+ * @returns {object} A jsPsych timeline object
  */
 export function buildHoneycombTimeline(jsPsych) {
   // Build the trials that make up the start procedure
@@ -47,8 +48,12 @@ export function buildHoneycombTimeline(jsPsych) {
   // Builds the trials that make up the end procedure
   const endProcedure = buildEndProcedure(jsPsych);
 
+  // Builds a countdown trial that counts down for 3000ms
+  const countdownTrial = buildCountdownTrial(3000);
+
   const timeline = [
     startProcedure,
+    countdownTrial,
     preloadTrial,
     instructionsTrial,
     honeycombProcedure,

src/experiment/index.js

@@ -1,6 +1,6 @@
 /**
  * ! Your timeline and options should be built in a newly created file, not this one
- * TODO @brown-ccv: Link "Quick Start" step once's it's built into the docs
+ * https://brown-ccv.github.io/honeycomb-docs/docs/quick_start#2-add-a-file-for-the-task
  */
 import { buildHoneycombTimeline, honeycombOptions } from "./honeycomb";
 
@@ -20,7 +20,7 @@ export const jsPsychOptions = honeycombOptions;
 /**
  * Builds the experiment's timeline that jsPsych will run
  * The instance of jsPsych passed in will include jsPsychOptions from above
- * @param {Object} jsPsych The jsPsych instance that is running the experiment
+ * @param {JsPsych} jsPsych The jsPsych instance that is running the experiment
  * @param {string} studyID The ID of the study that was just logged into
  * @param {string} participantID The ID of the participant that was just logged in
  * @returns The timeline for JsPsych to run
@@ -30,7 +30,7 @@ export function buildTimeline(jsPsych, studyID, participantID) {
 
   /**
    * ! Your timeline should be built in a newly created function, not this one
-   * TODO @brown-ccv: Link "Quick Start" step once's it's built into the docs
+   * https://brown-ccv.github.io/honeycomb-docs/docs/quick_start#2-add-a-file-for-the-task
    */
   const timeline = buildHoneycombTimeline(jsPsych);
   return timeline;

src/experiment/procedures/endProcedure.js

@@ -8,7 +8,7 @@ import { exitFullscreenTrial } from "../trials/fullscreen";
  * 1) Trial used to complete the user's camera recording is displayed
  * 2) The experiment exits fullscreen
  *
- * @param {Object} jsPsych The jsPsych instance being used to run the task
+ * @param {JsPsych} jsPsych The jsPsych instance being used to run the task
  * @returns {Object} A jsPsych (nested) timeline object
  */
 export function buildEndProcedure(jsPsych) {

src/experiment/procedures/honeycombProcedure.js

@@ -12,7 +12,7 @@ import { buildFixationTrial } from "../trials/fixation";
  *
  * Note that the block is conditionally rendered and repeated based on the task settings
  *
- * @param {Object} jsPsych The jsPsych instance being used to run the task
+ * @param {JsPsych} jsPsych The jsPsych instance being used to run the task
  * @returns {Object} A jsPsych (nested) timeline object
  */
 export function buildHoneycombProcedure(jsPsych) {

src/experiment/procedures/startProcedure.js

@@ -15,7 +15,7 @@ import { introductionTrial } from "../trials/introduction";
  * 4) Trials used to set up a photodiode and trigger box are displayed (if applicable)
  * 5) Trials used to set up the user's camera are displayed (if applicable)
  *
- * @param {Object} jsPsych The jsPsych instance being used to run the task
+ * @param {JsPsych} jsPsych The jsPsych instance being used to run the task
  * @returns {Object} A jsPsych (nested) timeline object
  */
 export function buildStartProcedure(jsPsych) {

src/experiment/trials/camera.js

@@ -9,7 +9,7 @@ const WEBCAM_ID = "webcam";
 
 /**
  * A trial that begins recording the participant using their computer's default camera
- * @param {Object} jsPsych The jsPsych instance being used to run the task
+ * @param {JsPsych} jsPsych The jsPsych instance being used to run the task
  * @returns {Object} A jsPsych trial object
  */
 // TODO @brown-ccv #301: Use jsPsych extension, deprecate this function

src/experiment/trials/countdown.js

@@ -0,0 +1,33 @@
+import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
+import { h1 } from "../../lib/markup/tags";
+import { getTimeString } from "../../lib/utils";
+
+/**
+ * a sample countdown trial that counts down ms before another trial begins
+ *
+ * @param {number} ms - millisecond to countdown
+ * @returns a JS object as a trial
+ */
+export function buildCountdownTrial(waitTime) {
+  return {
+    type: htmlKeyboardResponse,
+    stimulus:
+      h1("The next part of the experiment will start in") +
+      h1(getTimeString(waitTime), {
+        id: "clock",
+      }),
+    choices: "NO_KEYS",
+    trial_duration: waitTime + 20,
+    on_load: function () {
+      const startTime = performance.now();
+      const interval = setInterval(function () {
+        const timeLeft = waitTime - (performance.now() - startTime);
+        document.querySelector("#clock").innerHTML = getTimeString(timeLeft);
+        if (timeLeft <= 0) {
+          document.querySelector("#clock").innerHTML = "0:00";
+          clearInterval(interval);
+        }
+      }, 250);
+    },
+  };
+}

src/experiment/trials/fixation.js

@@ -1,13 +1,12 @@
 import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
-
 import { SETTINGS, config } from "../../config/main";
 import { eventCodes } from "../../config/trigger";
 import { pdSpotEncode, photodiodeGhostBox } from "../../lib/markup/photodiode";
 import { div } from "../../lib/markup/tags";
 
 /**
  * Builds a trial with a fixation dot and optional photodiode box.
- * @param {Object} jsPsych The global jsPsych object used to build the trial
+ * @param {JsPsych} jsPsych The global jsPsych object used to build the trial
  * @returns {Object} A jsPsych trial object
  */
 export function buildFixationTrial(jsPsych) {

src/experiment/trials/fullscreen.js

@@ -7,6 +7,12 @@ import jsPsychFullscreen from "@jspsych/plugin-fullscreen";
 export const enterFullscreenTrial = {
   type: jsPsychFullscreen,
   fullscreen_mode: true,
+  on_finish: (data) => {
+    // Record some additional information about the user's screen
+    data.screen_width = screen.width;
+    data.screen_height = screen.height;
+    data.screen_pixel_ratio = window.devicePixelRatio;
+  },
 };
 
 /**

src/experiment/trials/introduction.js

@@ -1,7 +1,7 @@
 import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
 
 import { LANGUAGE } from "../../config/main";
-import { div, h1 } from "../../lib/markup/tags";
+import { div, p, h1 } from "../../lib/markup/tags";
 
 /** Task that displays a introduction message with the photodiode ghost box */
 export const introductionTrial = {
@@ -11,5 +11,5 @@ export const introductionTrial = {
     const introductionMarkup = h1(LANGUAGE.trials.introduction);
     return div(introductionMarkup);
   },
-  prompt: LANGUAGE.prompts.continue.prompt,
+  prompt: p(LANGUAGE.prompts.continue.prompt),
 };

src/lib/typedef.js

@@ -0,0 +1 @@
+/** @typedef {import("jspsych").JsPsych} JsPsych */