Controlling Lollybot

Tom Tilley edited this page May 14, 2015 · 2 revisions
Clone this wiki locally

Introduction

Lollybot's control software consists of two parts - a server that simply handles communication with the the robot and a client web-page that displays telemetry information and sends commands for the robot to the server. You can find more information about how it works on this page.

The web-page controls the robot and it is implemented using three files:

  • index.html which is the HTML code for the page. You can modify this file if you need to add any new buttons, input fields, or interface controls. The existing page includes a panel to help you get started implementing your own mode that contains a Start/Stop button:

your-mode

  • lollybot-control.js in the 'scripts/' directory which contains the JavaScript code to control the robot as well as code for things like animating the control panels. This is where you can add your own code to control Lollybot's behaviour.

  • lollybot.css in the 'css/' directory which contains CSS code used to describe the style of some of the web-page elements.

Writing Your Own Control Mode

There are three main ways to add your own code to control Lollybot. You can add code that will be run:

  1. as soon as you press the "Start" button on the "Your Mode!" panel,
  2. when one of Lollybot's buttons is pressed, or
  3. when Lollybot's thumbsticks (which are usually wired to sensors) "move".

To add your own code you will need to download Lollybot's control and telemetry software and modify the 'lollybot-control.js' JavaScript file which is in the 'scripts/' directory.

1. Adding Code That Runs When You Press the "Start" Button

To add code that is run when you press the "Start" button, find this comment in 'lollybot-control.js':

// Add code to be run when the "Start" button is pressed here!

You can add your own code to be executed at this point or you could call another function. For example, there is a function called sendMessage() that will send a message to be displayed on the console from the robot. You could add some code to send a message to the server when your mode starts like this:

// Add code to be run when the "Start" button is pressed here!
sendMessage("My mode started!");

or, you could call your own control function:

// Add code to be run when the "Start" button is pressed here!
myControlFunction();

Whenever a mode starts (e.g "Driving" mode) then a variable called mode is updated with the name of the current mode. The mode name for your mode is "New". When the "Stop" button is pressed then the mode name is changed to "Undefined". You can check the value of the mode variable to see if your mode should stop running. For example:

function myControlFunction () {

  if (mode != "New") {
    return();  // exit the function if we are not in "New" mode 
  }

  // Do something here

}

2. Adding Code That Runs When a Button is Pressed

To add code that is run in response to a button press, find this comment in 'lollybot-control.js':

// Add code that responds to button presses here!

Whenever a button is pressed or released on the robot (or the buttons could be wired to other sensors so it appears that they are being pressed/released) then the server sends a message containing the current state of all the buttons. This information is copied into an array called buttonPressed that contains the value 'true' for any button that is currently pressed and 'false' if the button is not pressed.

On most joysticks there are 17 buttons (including the 'Analog' mode button) and you can check their state in buttonPressed where:

buttonPressed[0] is button 1

...

buttonPressed[11] is button 12

buttonPressed[12] is Up on the D-pad

buttonPressed[13] is Right on the D-pad

buttonPressed[14] is Down on the D-pad

buttonPressed[15] is Left on the D-pad

buttonPressed[16] is the Analog button (note that this is not reported by all joysticks)

For example, to run some code when button 3 is pressed you could modify the code like this:

// Add code that responds to button presses here!
if (buttonPressed[2]) {
  sendMessage("Button 3 pressed!");
}

3. Adding Code That Runs When a Thumbstick "Moves"

To add code that is run when a thumbstick moves or a sensor changes value, find this comment in 'lollybot-control.js':

// Add code that responds to thumbstick "movement" here!

As with the buttons described above, whenever the value of one of the thumbsticks (or a sensor wired in place of the thumbstick) changes a message is sent from the server containing the values for each of the joystick's axes. These are copied into an array called analogJoyValues with integer values between 0..255 where:

analogJoyValues[0] is the left thumbstick's X-axis

analogJoyValues[1] is the left thumbstick's Y-axis

analogJoyValues[2] is the right thumbstick's X-axis

analogJoyValues[3] is the right thumbstick's Y-axis

The center position for each of the joysticks has the value 127 (or 128 in analog mode), so for an X-axis:

values < 127 are to the left

values > 128 are to the right

and for a Y-axis:

values < 127 are in the up direction

values > 128 are in the down direction.

Note that if the joystick is not in analog mode then these values will only be 0 (hard left or up), 127 (centered), or 255 (right or down). To get the full range of analog values from 0 to 255 the joystick must be in analog mode (usually indicated by an LED near the 'analog' button.

For example, to send a message about the direction of the left thumbstick's X-axis to the server console you could modify the code like this:

// Add code that responds to thumbstick "movement" here!
if (analogJoyValues[0] < 127) {
  sendMessage("left");
} else if (analogJoyValues[0] > 128) {
  sendMessage("right");
}

Controlling the Motors

Lollybot has two motors which drive the wheels. These motors have an adjustable power level from 0 (off) up to 255 (maximum power), however, the motors are not very strong and only power levels close to the maximum will cause the wheels to turn.

To turn the motors on you must first set the desired power level of two variables leftMotorPower and rightMotorPower then send these levels to the robot using the sendMotorPower() function. For example, you can start the robot moving forward like this:

leftMotorPower  = 255; // set the left motor power level
rightMotorPower = 255; // set the right motor power level
sendMotorPower();

To stop the robot you can simply set both power levels to 0 like this:

leftMotorPower  = 0;
rightMotorPower = 0; 
sendMotorPower();

or there is a single function that does the same thing called stopMotors:

stopMotors();

You can make Lollybot turn by setting the motors to different power levels. For a sharp turn you can set one motor power level to 0 and the other to 255. If the left motor power level is greater then the right level then Lollybot will turn left:

leftMotorPower  = 255;
rightMotorPower = 0; 
sendMotorPower();

If the right motor power is greater than the left then Lollybot will turn right:

leftMotorPower  = 0;
rightMotorPower = 255; 
sendMotorPower();

If you have come up with an alternative design for your robot then there is an option to swap the motors on the settings panel:

settings

This will send the left motor power level to the right motor and the right motor power level to the left motor.

There are also functions to turn the motor on for a set period of time. See below for a summary of all the functions available to control the motors.

sendMotorPower()

This function will send the current value of the two variables leftMotorPower and rightMotorPower to the robot's motors. See the examples above.

stopMotors()

This function stops both motors by setting the value of the variables leftMotorPower and rightMotorPower to 0 and then sending them to the robot.

moveForward(milliSec)

This function makes the robot drive forward for milliSec milliSeconds at maximum power.

turnLeft(milliSec)

This function makes the robot turn left by turning on the left motor for milliSec milliSeconds at maximum power.

turnRight(milliSec)

This function makes the robot turn right by turning on the right motor for milliSec milliSeconds at maximum power.

runMotors(leftPower, rightPower, milliSec)

This function will turn on both motors at the given power levels for milliSec milliSeconds.

Executing a List of Commands

Sometimes you want to be able to run a number of commands in sequence. For example, you may want the robot to turn left, move forward, and then turn right, in that order. This can be done by adding commands to a list or queue using the addToQueue() function. You can then run the commands in the queue by calling the nextQueueCommand() function like this:

addToQueue(function(){turnLeft(1500)});
addToQueue(function(){moveForward(1500)});
addToQueue(function(){turnRight(1500)});
nextQueueCommand(); 

There are also functions to clear the queue (clearQueue()) and pause the queue (pauseQueue()). The queue functions are summarised below.

addToQueue(function(){})

This function will add the function named to the end of the command queue. See the example above.

nextQueueCommand()

Calling this function will start processing the commands on the queue in order until the queue is empty. See the example above.

pauseQueue(milliSec)

Adding this command onto the queue will cause it to pause for the specified number of milliSeconds. For example, you may want Lollybot to move forward when the up button is pressed on the D-pad but you need some time to move your finger away. You could write some code like this:

// Add code that responds to button presses here!
if (buttonPressed[12]) {
  addToQueue(function(){pauseQueue(500)}); // pause for 1/2 second
  addToQueue(function(){moveForward(1500)});
  nextQueueCommand();
} 

clearQueue()

Calling this function empties the queue and any functions on the queue that have not already started running will be removed. This function gets called automatically to clear the queue when the "Stop" button is pressed in the "Your Mode" panel.

Other Useful Commands

playBumpSound()

This function will play the bump sound that can be selected via the Bump mode panel (see below). Note that the 'Use bump sound' checkbox must be selected and different browsers support different audio formats. See the README.txt file in the 'audio/' directory for a list of the formats supported by different browsers.

bump-mode

sendMessage(text)

This function will send a message to be displayed on the server console. For example:

sendMessage("Hello!");

will be displayed on the server console as:

Lollybot: Hello!

console.log(text)

It is often helpful when trying to find and fix problems in your code to be able to print the value of variables or other information. You can do this using the JavaScript 'log' function which can display information on a console in your web browser. For example, to see the current value of the right thumbsticks's X-axis you could write something like this:

console.log("Right X-axis = " + analogJoyValues[2]);

To see the values displayed you must open your browser's web developer console. You can open the web developer console via your browsers menu (usually under the 'Tools' option) or via key shortcuts. You can find a list of shortcuts for different browsers here.