🚗Man-In-The-Loop Obstacle Avoidance Tutorial-JavaScript

Rover PWM Motor Drive Tutorial

Learn how to command the motors using the Motor Hat provided in your Rover kit.

This guide requires no prior programming experience and users should focus more on the concepts being introduced versus getting lost in the minutia of the scripting language.

Overview

In this guide you will learn how to manipulate and control the Rover based on the following basic concepts:

1. How to generate PWM commands for the ROVER.

2. Understand how the different PWM settings affect motor drive and direction.

3. Visualize PWM concepts with an appreciation for generated outputs.

Mission

🤖 Lab: Robotics Speed & Control (rover.js)

In this lab, you will modify the JavaScript source code of your robot to see how variable speed affects handling, inertia, and "braking" distance.

🛠️ Step 1: Setting Up the Environment

1. Open Chrome DevTools: Press F12 or Ctrl+Shift+I in your browser. This will allow you to monitor the Console for any code errors.

2. Open the Source: Open rover.js in Visual Studio Code (or your preferred text editor).

3. Identify the Logic: Locate the function MoveMotors(MTR1_PWM, MTR2_PWM, MTR3_PWM, MTR4_PWM) in the script.

   This function controls all four motors by assigning a PWM value to each motor:

   • MTR1_PWM – Motor 1

   • MTR2_PWM – Motor 2

   • MTR3_PWM – Motor 3

   • MTR4_PWM – Motor 4

   PWM values control both speed and direction and must be within the range -100 to 100:

   • 100 → Full speed forward

   • 0 → Stop

   • -100 → Full speed backward

   • Values closer to 0 move slower; values closer to ±100 move faster

   Example Motor Commands (Range: -100 to 100)

   Movement	MTR1_PWM	MTR2_PWM	MTR3_PWM	MTR4_PWM	Description
   Forward	100	100	100	100	All motors move forward at full speed
   Forward (slow)	50	50	50	50	All motors move forward at half speed
   Backward	-100	-100	-100	-100	All motors move backward at full speed
   Turn Right	100	-100	100	-100	Left motors forward, right motors backward
   Turn Left	-100	100	-100	100	Left motors backward, right motors forward
   Stop	0	0	0	0	All motors stopped

Step 2: Modifying the Code

Default Speed Inputs: The motor speed inputs passed to the MoveMotors(MTR1_PWM, MTR2_PWM, MTR3_PWM, MTR4_PWM) function are typically set to 100 and -100, which represent full speed forward and full speed backward. These values are set in Rover.html.

Task: Modify the PWM input values passed into the MoveMotors() function in increments of 25, staying within the valid range of -100 to 100. For example, test values such as:

• 25 and -25

• 50 and -50

• 75 and -75

• 100 and -100

Example:

MoveMotors(50, 50, 50, 50);   // Forward at medium speed
MoveMotors(-50, -50, -50, -50); // Backward at medium speed

Update: After each change:

1. Save the rover.js file

2. Reload the rover.html page in your browser

3. Reconnect to your ROV control board

Test: Attempt the obstacle course using each PWM setting. Observe how different input values affect the rover’s speed and control. Lower values allow more precise movement, while higher values increase speed.

---

🧐 Critical Thinking & Observations

🛑 1. Where are the brakes?

If you look closely at the stop() function, you'll see it simply sets the speed to 0.

The Reality: There are no active mechanical brakes. The robot stops because of friction and inertia. At high speeds, the robot will "drift" or slide forward even after the power is cut.

🛣️ 2. Speed vs. Handling (The "Highway" Effect)

Why do highway ramps have maximum speed signs?

• Centrifugal Force: At high speeds, the robot (or a car) wants to keep moving in a straight line.

• Control: Just like your robot, a car requires more distance to turn or stop as speed increases. High-speed settings make the robot "twitchy" and harder to navigate through tight obstacles.

📶 3. The "Remote Link" (Latency)

In a car, your foot hits the brake and the response is nearly instant. In this lab, your command must travel through:

1. JavaScript Execution $→$ 2. Browser Processing $→$ 3. Wi-Fi/Bluetooth Signal $→$ 4. SCT Board.

• The Lag: If there is even a half-second delay (latency), the robot may hit a wall before the "Stop" command ever reaches the wheels.

---

🏁 Time Trials: Leaderboard

Record your fastest clean run (no collisions!) for each speed setting.

Team Name	Speed Setting	Completion Time	Collisions

Export to Sheets

---

To access the program, simply follow this link https://mantiscode.azurewebsites.net/webble/joystick/roverse/rover.html.

This Rover GUI code demo contains two files:

rover.html

o This must be in the same folder as the JavaScript file

o Contains metadata about the extension and how to configure all the Gui items in the browser.

rover.js

o This module contains the underlying BLE communications.

o We will be iteratively modifying the functions specific to the Joystick buttons above.

Connect ROV Board

Click on the Bluetooth icon and make sure your device is broadcasting. Once broadcasting, click on the pair button to connect to the board.

Once you have a successful connection, the interface will report that a connection was successful.

After connecting, use the arrow keys to move the motors. Notice how the motors move as your move the commands. Press the stop button to cease all motion.

Rover.html Breakdown

Let's break down the contents of mthjoystick.html file. This code tells your browser how and where to place everything that you see on the screen demonstrated above. You can copy this code directly into a text editor and make sure to name it with the same convention above.

rover.html

<!doctype html>
<html>

    <head>
        <title>RoverSE Control Panel</title>

        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/material-design-lite/1.3.0/material.indigo-pink.min.css">
        <script defer src="https://cdnjs.cloudflare.com/ajax/libs/material-design-lite/1.3.0/material.min.js"></script>

      <style>

            body {
              background: #fff;
            }
            
            .mip-layout {
              display: flex;
              align-items: center;
              justify-content: center;
              background: #fff;
            }
            
            .mip-card {
              width: 400px;
            }
            
            .mip-pad {
              display: flex;
              align-items: center;
              flex-direction: column;
            }
            
            .mip-pad button {
              margin: 1em 0.5em;
            }
            
            
            #logTextArea {
              width: 950%;
              height: 150px;
              overflow: auto;
            }
            
                    </style>

<style>
    #joystickZone {
      width: 300px;
      height: 300px;
      background: #eee;
      border-radius: 50%;
      margin: 50px auto;
      position: relative;
    }
    #output,#distance {
      text-align: center;
      font-size: 1.2em;
    }
     #output {
      text-align: center;
      font-size: 1.2em;
    }
  </style>
    </head>

    <body>


        <div class="mip-layout mdl-layout mdl-js-layout">

            <div class="mdl-card mdl-shadow--2dp mip-card">
                <div class="mdl-card__title">
                    <h3 class="mdl-card__title-text">Mantis RoverSE</h3>
                </div>
                <div class="mdl-card__supporting-text">
                </div>
                <div class="mdl-card__actions mdl-card--border mip-pad">

                    <button onclick="MoveMotors(30,30,30,30)" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                        <i class="material-icons">arrow_upward</i>
                    </button>

                    <div>
                        <button onclick="MoveMotors(30,30,-30,-30)" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                            <i class="material-icons">arrow_back</i>
                        </button>

                        <button id="bluetoothBtn" onclick="connect()" class="mdl-button mdl-js-button mdl-button--fab mdl-button--colored">
                            <i class="material-icons">bluetooth_searching</i>
                        </button>

                        <button onclick="MoveMotors(-30,-30,30,30)" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                            <i class="material-icons">arrow_forward</i>
                        </button>
                    </div>

                    <button onclick="MoveMotors(-30,-30,-30,-30)" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                        <i class="material-icons">arrow_downward</i>
                    </button>
				

                </div>
                <div class="mdl-card__actions mdl-card--border" align="center">
                    <button onclick="stop()">
                        Stop
                    </button>

                    <button onclick="StartProgram()">Run My Program

                    </button>
                     <button onclick="disconnect()">
                        Disconnect Device
                    </button>
                    <div id="output" class="mdl-card__supporting-text">M1: 0 | M2: 0 | M3: 0 | M4: 0</div>
                    <div id="distance" class="mdl-card__supporting-text">Distance: 0mm</div>
                </div>
                 <div class="mdl-card__actions mdl-card--border" align="center">
                    <button onclick="EnableTelemetry('on')">
                        Enable Telemetry 
                    </button>
                    <button onclick="ModiState('on')">
                        Modi On
                    </button>
                    <button onclick="ModiState('off')">
                        Modi Off
                    </button>
                </div>
                <textarea id="logTextArea" readonly></textarea>
            </div>
           
        </div>
        

        <script src="rover.js?id=2S"></script>
    </body>

</html>

For starters you can see where the buttons are called out here starting on line 1, four buttons in total and one for each direction we desire to move the Rover. There are a number of styles and types that can be used to configure these buttons for a different shape and feel in the future.

 <button onclick="moveForward()" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                        <i class="material-icons">arrow_upward</i>
                    </button>

                    <div>
                        <button onclick="turnLeft()" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                            <i class="material-icons">arrow_back</i>
                        </button>

                        <button onclick="connect()" class="mdl-button mdl-js-button mdl-button--fab mdl-button--colored">
                            <i class="material-icons">bluetooth_searching</i>
                        </button>

                        <button onclick="turnRight()" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                            <i class="material-icons">arrow_forward</i>
                        </button>
                    </div>

                    <button onclick="moveBackward()" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
                        <i class="material-icons">arrow_downward</i>
                    </button>

rover.js Breakdown

The man-in-the-loop experiment calls for manipulating the drive strength of these buttons and observing the results as you maneuver around the obstacle course that you made. It is important when you learn to code that you appreciate certain aspects of the code while focusing your efforts on the specific regions of concern. All other sections in the mthjoystick.js javascript file maintain very low level details of the BLE layer that is beyond the scope of this exercise. Before proceeding further go ahead and copy this code into a text editor in its entirety and save it with the exact naming convention above.

rover.js

'use strict';

var mDev=null;
var Distance=null;

var isConnected=false;
var StopProgram = false; // Flag to stop the program
const originalLog = console.log;

const logTextArea = document.getElementById("logTextArea");


let isGATTOperationInProgress = false; // Lock to prevent overlapping GATT operations
setButtonsEnabled(false); // Disable buttons initially



// Override console.log to append logs to the text area
console.log = function() {
  // Convert all arguments to a single string
  const message = Array.from(arguments).map(arg => String(arg)).join(" ");

  // Append the log message to the text area
  logTextArea.value += message + "\n";
  logTextArea.scrollTop = logTextArea.scrollHeight;
  // Call the original console.log
  originalLog.apply(console, arguments);

};


function connect() {
    console.log('Requesting RoverSE Device...');
    if (!navigator.bluetooth) {
        alert('Web Bluetooth is disabled! Please go to enable it.');
        return;
    }

   // console.log("Filtering on BLE device name: " + dev + " Service: " + mDev.PrimaryService);
    navigator.bluetooth.requestDevice({
        filters: [{ namePrefix: "ROV" }],
        optionalServices: ['0000ffd0-0000-1000-8000-00805f9b34fb']
    })
        .then(device => {
          //  console.log("device:");
           // console.log(device);
            let deviceprefix=device.name.split("_")[0];
            mDev = new MantisDevice(deviceprefix.toLowerCase());
            device.addEventListener('gattserverdisconnected', onDisconnected);

          // Connect to the GATT server and get the services
            device.gatt.connect().then(server => {
                // Get the Service
               mDev.device = device;
               // console.log("Primary Service Requested: " + mDev.PrimaryService);
                // mDev.primaryServiceObj = server.getPrimaryService(mDev0.PrimaryService);
                server.getPrimaryService(mDev.PrimaryService)
                    .then(service => {
                        mDev.primaryServiceObj = service;
                     //   console.log("got service");
                        //Set the disconnection callback
                        if ((mDev.NotificationChar != null) && (notificationCallback != null)) {
                            service.getCharacteristic(mDev.NotificationChar)
                                .then(notifyChar => {
                              //      console.log("got notify characteristic");
                                    notifyChar.addEventListener('characteristicvaluechanged',notificationCallback);
                                    mDev.notificationCharObj = notifyChar;
                                    mDev.notificationCharObj.startNotifications()
                                    .catch(error => {
                                        console.error("Error turning on notifications: " + error.message)
                                    })
                                })
                        }
                        if (mDev.InitializationChar != null) {
                            service.getCharacteristic(mDev.InitializationChar)
                                .then(initChar => {
                                 //   console.log("got initialize characteristic");
                                    mDev.initializationCharObj = initChar;
                                })
                        }
                        if (mDev.MailboxChar != null) {
                            service.getCharacteristic(mDev.MailboxChar)
                                .then(mailboxChar => {
                               //     console.log("got mailbox characteristic");
                                    mDev.mailboxCharObj = mailboxChar;
                                })
                        }

                        if (mDev.CommandChar != null) {
                            service.getCharacteristic(mDev.CommandChar)
                                .then(commandChar => {
                                    isConnected=true;
                                  //  console.log("got command characteristic");
                                    mDev.commandCharObj = commandChar;
                                    console.log("Connected!");
                                   
                                     initialize().then(result => {
                                        console.log("Awaiting Commands!");
                                        });
                                     setButtonsEnabled(true); // Enable buttons after connection
                                })
                        }
                       

                    })
                    .catch(error => {
                        console.error("Failed to get services: " + error.message);
                    });
            })
                .catch(error => {
                    console.error("Error requesting device: " + error.message)
                })
        })

      //  console.log(mDev);
 
}

async function initialize() {
    await MoveMotors(-1, -1, -1, -1);
    await MoveMotors(0, 0, 0, 0);
}

function disconnect() {
    if (mDev && mDev.device && mDev.device.gatt.connected) {
        console.log("Disconnecting from device...");
        mDev.device.gatt.disconnect();
     
    } else {
        console.log("No device connected to disconnect.");
    }
}
function onDisconnected(event) {
    isConnected = false;
    console.log("Device disconnected.")
    console.log("Click the bluetooth icon to reconnect.");
   // document.getElementById('output').textContent = 'Device disconnected';
    setButtonsEnabled(false); // Disable buttons on disconnect
    //setBluetoothButtonToConnect();
    // Optionally, reset UI or attempt reconnection here
}


async function writeBytesUUID(characteristic, bytes) {
    try {
        await characteristic.writeValue(bytes)
       // console.log('Success')
        // Return a value, for example, a success message or the payloads
        return { success: true };
    } catch (error) {
        // Handle any errors that occur during the asynchronous operations
       // console.log('Error:' + error.message)
        return { success: false, error };
    }
}

 async function movecmd(payload_cmd, payload_data) {
        const startTime = Date.now(); // Record the start time

        const result = await writeBytesUUID(mDev.mailboxCharObj, payload_data);
        //console.log("Send Mailbox:" + payload_data)
        
           // const hexPayload = payload_data.toString(16);
            //console.log("Send Mailbox hex:" + hexPayload); 
        
        if (result.success) {
            //console.log("Send Command:" + payload_cmd)
            await writeBytesUUID(mDev.commandCharObj, payload_cmd);
           
        } else {
            console.log("Error don't sent Command:" + payload_cmd)
            console.error(result.error.message);
        }


    }




  function MantisDevice (devName1) {
  
   
   // console.log("DeviceName: " + devName1.split("_")[0]);
    switch (devName1) {
       case "rov":
        this.PrimaryService =     '0000ffd0-0000-1000-8000-00805f9b34fb';
        this.NotificationChar =   '0000ffd4-0000-1000-8000-00805f9b34fb';
        this.MailboxChar = '0000ffd1-0000-1000-8000-00805f9b34fb';
        this.CommandChar = '0000ffd2-0000-1000-8000-00805f9b34fb';
      break;
      //default:
   //       console.log("Dev Init: Unknown device, doing nothing: " + devName1);
  }
  
  
    this.primaryServiceObj =     null;
    this.notificationCharObj =   null;
    this.initializationCharObj = null;  
    this.mailboxCharObj = null;  
    this.commandCharObj = null; 
    this.device=null;
  
  
   // console.log(this);
  }

 
  

  function notificationCallback(event) {
    let value = event.target.value;
    let a = [];
    // Convert raw data bytes to hex values just for the sake of showing something.
    // In the "real" world, you'd use data.getUint8, data.getUint16 or even
    // TextDecoder to process raw data bytes.
    
    for (let i = 0; i < value.byteLength; i++) {
      a.push('0x' + ('00' + value.getUint8(i).toString(16)).slice(-2));	
    }
    if (a[0] == "0x01") {//distance packet
       Distance = toUInt16(bitConverter(a, 14, 15));
       const distance = (a[13] << 8) | a[12];
       //console.log('data: ' + a);
       //console.log("Distance: " + Distance);
      document.getElementById('distance').textContent =`Distance: ${Distance}mm`;

    }
  
    
  }

  var bitConverter = function bitConverter (arr, start, end) {
    var populate = function populate () {
        var data = [];
        for (var i = start; i <= end; i++) {
            (function (val) {
                data.push(arr[val]);
            })(i);
        }
        return data;
    };
    var combine = function combine (data, index) {
        if (index >= 0) {
            var tmp = data[index] << (index << 3);
            return tmp | combine(data, --index);
        } else {
            return 0;
        }
    };
    if (start >= 0 && start < arr.length && end > 0 && end < arr.length) {
        return combine(populate(), arr.length - 1);
    } else {
        throw Error('Invalid parameters to bitConverter: start: ' + start + ' end: ' + end + ' arr.length: ' + arr.length);
    }
};
/**
 * A function to treat a 16 bit integer as two's complement signed
 *
 * @param val A 16 bit integer
 * @returns {int} The parameter converted to its two's complement signed value
 */
var toSignedInt16 = function toSignedInt16 (val) {
    return (new Int16Array([val]))[0];
};

var toUInt16=function toUInt16(val) {
    return (new Uint16Array([val]))[0];
};



function setButtonsEnabled(enabled) {
    // Exclude the Bluetooth/connect button from being disabled
    const buttons = document.querySelectorAll('button');
    buttons.forEach(btn => {
        if (btn.id !== 'bluetoothBtn') { // Change 'bluetoothBtn' to your actual button's id
            btn.disabled = !enabled;
        }
    });
}



 function ModiState(modistate) { 
  
    let byte2='';
    if (modistate == 'on') {
        byte2 = 0x01;
    }
    else {
        byte2 = 0x00;
    }

   // console.log("byte2 " + byte2);
    let payload2 = new Uint8Array(2);
    payload2[0] = 0x00;
    payload2[1] = byte2;
    writeBytesUUID(mDev.mailboxCharObj, payload2);
    
    let payload3 = new Uint8Array(2);
    payload3[0] = 0x0D;
    payload3[1] = 0x00;
    
     setTimeout(function () {
         self.writeBytesUUID(mDev.commandCharObj, payload3);
     //    console.log("Executed CMD after 300 MS delay");
     }, 300);//timeout
 
     console.log("Turning Modi '"+ modistate+ "' and Restarting Device:")
 
 
 }

 function EnableTelemetry(state) { 
  
    let byte1='';
    if (state == 'on') {
        byte1 = 1;
    }
    else {
        byte1 = 0;
    }

    let payload2 = new Uint8Array(1);
    payload2[0] = byte1 ;
    writeBytesUUID(mDev.mailboxCharObj, payload2);
    
    let payload3 = new Uint8Array(2);
    payload3[0] = 0x19;
    payload3[1] = 0x00;
    
     setTimeout(function () {
         self.writeBytesUUID(mDev.commandCharObj, payload3);
     //    console.log("Executed CMD after 300 MS delay");
     }, 300);//timeout
 
     console.log("Telemetry State:" + state)
 
 }

  

async function stop(){
    MoveMotors(0,0,0,0)
    StopProgram=true;
}




async function MoveMotors(MTR1_PWM, MTR2_PWM, MTR3_PWM, MTR4_PWM) {

    const payloadMailbox = new Uint8Array(4);
    const payloadCmd = new Uint8Array(2);
    payloadCmd[0] = 0x13; // controls both motors
    payloadCmd[1] = 0x00;
     // Wait until the lock is released
     if (isGATTOperationInProgress) {
        return
    }

    isGATTOperationInProgress = true; // Acquire the lock
    payloadMailbox[0] = MTR1_PWM;
    payloadMailbox[1] = MTR2_PWM;
    payloadMailbox[2] = MTR3_PWM;
    payloadMailbox[3] = MTR4_PWM;

 
    try {
        // Use the movecmd function to send the command
        await movecmd(payloadCmd,payloadMailbox);
    
        await delay(0.1); // if no movement, wait a short time
        
       document.getElementById('output').textContent =
       `M1: ${MTR1_PWM} M2: ${MTR2_PWM} M3: ${MTR3_PWM} M4: ${MTR4_PWM}`;
   
    } catch (error) {
        console.error("Error in MoveMotors:", error.message);
    } finally {
        isGATTOperationInProgress = false; // Release the lock
    }
}





 function toLittleEndian2Bytes(num) {
        const buffer = new ArrayBuffer(2);
        const view = new DataView(buffer);
        view.setUint16(0, num, true);
        return new Uint8Array(buffer);
}

// Delay Helper Function
function delay(seconds) {
 // console.log(`delay for ${seconds} seconds...`);
  return new Promise(resolve => setTimeout(resolve, seconds * 1000));
}

async function StartProgram() {
  // Reset the stop flag so the program can run
  StopProgram = false;

  // Log what the robot is about to do
  console.log("Moving forward at 30% speed for 5 seconds");

  // Move all motors forward at 30% speed
  // M1 and M2 on one side, M3 and M4 on the other — same direction = forward
  await MoveMotors(30, 30, 30, 30);

  // Wait for 5 seconds while the robot moves
  await delay(5);

  // Log the stopping action
  console.log("Stopping all motors");

  // Stop all motors by setting their speed to 0
  await MoveMotors(0, 0, 0, 0);
}

man-in-the-loop exercise

To make this experiment more consistent, we will set the same PWM strength for all motors using the MoveMotors(MTR1_PWM, MTR2_PWM, MTR3_PWM, MTR4_PWM) function directly in the HTML buttons.

For example:

<button onclick="MoveMotors(30,30,30,30)" class="mdl-button mdl-js-button mdl-button--fab mdl-button--raised mdl-js-ripple-effect">
    <i class="material-icons">arrow_upward</i>
</button>

This command sets all four motors to a PWM value of 30, causing the rover to move forward at the same speed.

Experiment Procedure

Step 1: Save the Files Save the HTML file (rover.html) and JavaScript file (rover.js) to your local machine.

Step 2: Modify the PWM Values in the HTML Locate each button that calls the MoveMotors() function and update the PWM values so that all motors use the same strength. For example:

MoveMotors(25,25,25,25)
MoveMotors(50,50,50,50)
MoveMotors(75,75,75,75)
MoveMotors(100,100,100,100)

Ensure the values remain within the valid range of -100 to 100.

Step 3: Save and Reload

• Save the updated rover.html file

• Open or refresh the file in Google Chrome

• Connect to your Rover control board

Step 4: Run the Obstacle Course Use the GUI buttons to maneuver the rover through the obstacle course.

Step 5: Record Your Observations For each PWM setting, record:

• Number of obstacle collisions

• Ease of controlling the rover

• Ability to stay on course

• Overall responsiveness

Repeat the Experiment

Repeat Steps 2–5 using PWM strengths in increments of 25:

• 25 (slow speed)

• 50 (medium speed)

• 75 (fast speed)

• 100 (maximum speed)

This will help you observe how PWM strength affects rover speed, control, and precision.