MyroCDev
A C library for bluetooth communication with Scribbler 2 robots
 All Data Structures Files Functions Variables
Data Structures | Functions
MyroCDev.h File Reference

Header for a C-based, my-robot package for the Scribbler 2. More...

Go to the source code of this file.

Data Structures

struct  Pixel
 Struct for a pixel. More...
struct  Picture
 Struct for a picture object. More...

Functions

int rConnect (const char *address)
 connects program to Scribbler
void rDisconnect ()
 disconnect program from Scribbler
void rSetConnection (int socket_num)
 set current connection to the socket number
void rBeep (double duration, int frequency)
 Beeps with the given duration and frequency.
void rBeep2 (double duration, int freq1, int freq2)
 Generates two notes for the prescribed duration.
void rSetName (const char *name)
 Change name stored in the robot to the 16-byte name given.
const char * rGetName ()
 Get the name of the robot.
void rSetForwardness (char *direction)
 specifies which end of the Scribbler is considered the front
void rSetForwardnessTxt (char *direction)
 alternative to rSetForwardness for compatibility with earlier MyroC
char * rGetForwardness ()
 Gets the forwardness of the Scribbler.
void rSetLEDFront (int led)
 Set the front [fluke] LED on or off.
void rSetLEDBack (double led)
 Set the the intensity of the back fluke LED,.
double rGetBattery ()
 Get the percentage of volts left in the batteries of the scribbler.
int rGetStall (int sampleSize)
 Determine if robot has stalled Since readings of each brightness sensor can vary substantially, each sensor can be queried sampleSize times and an average obtained.
void rGetLightsAll (int lightSensors[3], int sampleSize)
 Get the average values of each of the three light sensors in an array. Values of each light sensor can somewhat (typically under 5%-10%). To even out variability, the sensor can be queried sampleSize times and an average obtained.
int rGetLightTxt (const char *sensorName, int sampleSize)
 Get the average values of a specified light sensor. Values of each light sensor can somewhat (typically under 5%-10%). To even out variability, the sensor can be queried sampleSize times and an average obtained.
void rGetIRAll (int irSensors[2], int sampleSize)
 Get an array of true/false values regarding the presence of obstacle based on the average values of each of the three IR sensors. Since readings of each light sensor can vary substantially, each sensor can be queried sampleSize times and an average obtained.
int rGetIRTxt (const char *sensorName, int sampleSize)
 Use specified IR sensor to determine if obstacle is present. Since values of each light sensor can vary substantially, the sensor can be queried sampleSize times and an average obtained.
void rGetLine (int lineSensors[2], int sampleSize)
 Use Scribbler 2 line sensors of Scribbler to check for a black line on a white surface under the robot. Since values of each light sensor can vary substantially, the sensor can be queried sampleSize times and an average obtained.
void rSetIRPower (int power)
 Set the amount of power for the dongle's IR sensors.
void rGetObstacleAll (int obstSensors[3], int sampleSize)
 Get the average values of the three obstacle sensors in an array. Since readings of each obstacle sensor can vary substantially (successive readings may differ by several hundred or more), each sensor can be queried sampleSize times and an average obtained.
int rGetObstacleTxt (const char *sensorName, int sampleSize)
 Get the average values of a specified obstacle (IR) sensor. Since values of each obstacle sensor can vary substantially (successive readings may differ by several hundred or more), the sensor can be queried sampleSize times and an average obtained.
void rGetBrightAll (int brightSensors[3], int sampleSize)
 Read the Fluke's virtual light sensors. Since readings of each brightness sensor can vary substantially (successive readings may differ by 5000-10000), each sensor can be queried sampleSize times and an average obtained.
int rGetBrightTxt (char *sensorName, int sampleSize)
 Reads one of the Fluke's virtual light sensors. Since values of each obstacle sensor can vary substantially (successive readings may differ by 5000-10000), the sensor can be queried sampleSize times and an average obtained.
void rGetInfo (char *infoBuffer)
 returns information about the robot's dongle, firmware, and communication mode as a 60 character array in infoBuffer.
void rTurnLeft (double speed, double time)
 turn Scribbler left for a specified time and speed
void rTurnRight (double speed, double time)
 turn Scribbler right for a specified time and speed
void rTurnSpeed (char *direction, double speed, double time)
 turn Scribbler in direction for a specified time and speed
void rForward (double speed, double time)
 moves Scribbler forward for a specified time and speed
void rFastForward (double time)
 moves Scribbler forward at the largest possible speed for a specified time
void rBackward (double speed, double time)
 moves Scribbler backward for a specified time and speed
void rMotors (double leftSpeed, double rightSpeed)
 move robot with given speeds for the left and right motors continues until given another motion command or disconnected (non-blocking)
void rStop ()
 directs robot to stop movement
void rHardStop ()
 cuts power to the motor of the robot
Picture rTakePicture ()
 Use the camera to take a photo.
void rSavePicture (Picture pic, char *filename)
 Save a Picture to a .jpeg.
Picture rLoadPicture (char *filename)
 Load a picture from a .jpeg file.
void rDisplayPicture (Picture pic, double duration, const char *windowTitle)
 Display a picture in a new window.

Detailed Description

Header for a C-based, my-robot package for the Scribbler 2.

Authors
Spencer Liberto
Dilan Ustek
Jordan Yuan
Henry M. Walker
Anita DeWitt
Jason Liu
Nick Knoebber
Vasilisa Bashlovkina

Based on a C++ package by April O'Neill, David Cowden, Dilan Ustek, Erik Opavsky, and Henry M. Walker

Note
There is an r in the beginning of every function to make it easier to understand whether it is a robot function.

Function Documentation

void rBackward ( double  speed,
double  time 
)

moves Scribbler backward for a specified time and speed

Parameters
speedthe rate at which the robot should move backward linear range: -1.0 specifies move forward at full speed 0.0 specifies no forward/backward movement 1.0 specifies move backward at full speed
timespecifies the duration of the turn if negative: robot continues to go backward until given another motion command or disconnected (non-blocking) if nonnegative: robot moves backward for the given duration, in seconds
void rBeep ( double  duration,
int  frequency 
)

Beeps with the given duration and frequency.

Parameters
durationlength of note in seconds
frequencyfrequency of pitch in cycles per second (hertz)
Precondition
duration > 0.0
void rBeep2 ( double  duration,
int  freq1,
int  freq2 
)

Generates two notes for the prescribed duration.

Parameters
durationlength of note in seconds
freq1frequency of first pitch in cycles per second (hertz)
freq2frequency of second pitch in cycles per second (hertz)
Precondition
duration > 0.0
int rConnect ( const char *  address)

connects program to Scribbler

Parameters
addressstring, giving name of workstation port or a Scribbler Bluetooth designation

several string formats are possible a communications port, such as "/dev/rfcomm0" a MAC address, such as "00:1E:19:01:0E:13" a Scribbler 2 fluke serial number, such as "245787" a full IPRE serial number, such as "IPRE245787" a Fluke 2 serial number (hexadecimal), such as "021F" a full Fluke 2 serial number, such as "Fluke2-021F"

Returns
the socket number of communications port
Postcondition
subsequent communications will take place through this socket, unless changed by rSetConnection
void rDisconnect ( )

disconnect program from Scribbler

void rDisplayPicture ( Picture  pic,
double  duration,
const char *  windowTitle 
)

Display a picture in a new window.

Parameters
picRGB picture struct from Scribbler 2 camera
durationif duration > 0, operation is blocking if duration <= 0, operation is non-blocking for duration != 0, picture displayed for abs(duration) seconds or until picture closed manually if duration == 0, picture displayed until closed manually
windowTitleThe title of the window that appears. white spaces will be replaced with underscores.
Precondition
windowTitle is less than 100 characters.
void rFastForward ( double  time)

moves Scribbler forward at the largest possible speed for a specified time

Parameters
timespecifies the duration of movement if negative: robot continues to move forward until given another motion command or disconnected (non-blocking) if nonnegative: robot moves forward for the given duration, in seconds
Warning
may take longer than usual to execute
void rForward ( double  speed,
double  time 
)

moves Scribbler forward for a specified time and speed

Parameters
speedthe rate at which the robot should move forward linear range: -1.0 specifies move backward at full speed 0.0 specifies no forward/backward movement 1.0 specifies move forward at full speed
timespecifies the duration of movement if negative: robot continues to move forward until given another motion command or disconnected (non-blocking) if nonnegative: robot moves forward for the given duration, in seconds
double rGetBattery ( )

Get the percentage of volts left in the batteries of the scribbler.

Returns
percentage of battery voltage
void rGetBrightAll ( int  brightSensors[3],
int  sampleSize 
)

Read the Fluke's virtual light sensors. Since readings of each brightness sensor can vary substantially (successive readings may differ by 5000-10000), each sensor can be queried sampleSize times and an average obtained.

Parameters
brightSensorsarray to store intensity values
sampleSizehow many readings are taken for each sensor
Precondition
space already allocated for brightSensors array sampleSize > 0
Postcondition
brightSensors[0] gives average value for left sensor brightSensors[1] gives average value for middle sensor brightSensors[2] gives average value for right sensor Brightness values near 0 represent bright light Brightness values may extend to about 65535 for a very dark region.
int rGetBrightTxt ( char *  sensorName,
int  sampleSize 
)

Reads one of the Fluke's virtual light sensors. Since values of each obstacle sensor can vary substantially (successive readings may differ by 5000-10000), the sensor can be queried sampleSize times and an average obtained.

Parameters
sensorNamename of the obstacle sensor
Precondition
sensorName is "left", "center", "middle", or "right" (not case sensitive) designations "center" and "middle" are alternatives for the same light sensor
Parameters
sampleSizehow many readings are taken for the sensor
Precondition
sampleSize > 0
Returns
reading from the specified obstacle sensor, averaged over sampleSize number of data samples Brightness values near 0 represent bright light Brightness values may extend to about 65535 for a very dark region.
char* rGetForwardness ( )

Gets the forwardness of the Scribbler.

Returns
either "fluke-forward" or "scribbler-forward"
void rGetInfo ( char *  infoBuffer)

returns information about the robot's dongle, firmware, and communication mode as a 60 character array in infoBuffer.

Parameters
infoBuffera pre-defined, 60-character array
Postcondition
infoBuffer contains relevant robot information
void rGetIRAll ( int  irSensors[2],
int  sampleSize 
)

Get an array of true/false values regarding the presence of obstacle based on the average values of each of the three IR sensors. Since readings of each light sensor can vary substantially, each sensor can be queried sampleSize times and an average obtained.

Parameters
irSensorsarray to store intensity values
sampleSizehow many readings are taken for each sensor
Precondition
space already allocated for irSensors array sampleSize > 0
Postcondition
irSensors[0] checks obstacle for left sensor irSensors[1] checks obstacle for right sensor
for each irSensors array value return 0 indicates no obstacle detected return 1 indicates obstacle detected
int rGetIRTxt ( const char *  sensorName,
int  sampleSize 
)

Use specified IR sensor to determine if obstacle is present. Since values of each light sensor can vary substantially, the sensor can be queried sampleSize times and an average obtained.

Parameters
sensorNamename of the light sensor
Precondition
sensorName is "left" or "right" (not case sensitive)
Parameters
sampleSizehow many readings are taken for the sensor
Precondition
sampleSize > 0
Returns
true/false (0/1) determination of obstacle, based on IR sensorName sensor, averaged over sampleSize number of data samples
Postcondition
return 0 indicates no obstacle detected return 1 indicates obstacle detected
void rGetLightsAll ( int  lightSensors[3],
int  sampleSize 
)

Get the average values of each of the three light sensors in an array. Values of each light sensor can somewhat (typically under 5%-10%). To even out variability, the sensor can be queried sampleSize times and an average obtained.

Parameters
lightSensorsarray to store intensity values
sampleSizehow many readings are taken for each sensor
Precondition
space already allocated for lightSensors array sampleSize > 0
Postcondition
lightSensors[0] gives average value for left sensor lightSensors[1] gives average value for middle sensor lightSensors[2] gives average value for right sensor Intensity values near 0 represent bright light Intensities may extend to about 65000 for a very dark region.
int rGetLightTxt ( const char *  sensorName,
int  sampleSize 
)

Get the average values of a specified light sensor. Values of each light sensor can somewhat (typically under 5%-10%). To even out variability, the sensor can be queried sampleSize times and an average obtained.

Parameters
sensorNamename of the light sensor
Precondition
sensorName is "left", "center", "middle", or "right" (not case sensitive) designations "center" and "middle" are alternatives for the same light sensor
Parameters
sampleSizehow many readings are taken for the sensor
Precondition
sampleSize > 0
Returns
reading from the specified light sensor, averaged over sampleSize number of data samples if sensorName invalid, returns -1.0
void rGetLine ( int  lineSensors[2],
int  sampleSize 
)

Use Scribbler 2 line sensors of Scribbler to check for a black line on a white surface under the robot. Since values of each light sensor can vary substantially, the sensor can be queried sampleSize times and an average obtained.

Warning
results of these sensors may be flakey!
Parameters
lineSensorsarray to store line values detected
sampleSizehow many readings are taken for each sensor
Precondition
space already allocated for lineSensors array sampleSize > 0
Postcondition
lineSensors[0] checks left sensor for line lineSensors[1] checks right sensor for line
for each irSensors array value return 0 indicates line is identified return 1 indicates line is not identified
const char* rGetName ( )

Get the name of the robot.

Returns
information about the name of the robot
Postcondition
the returned name is a newly-allocated 17-byte string
void rGetObstacleAll ( int  obstSensors[3],
int  sampleSize 
)

Get the average values of the three obstacle sensors in an array. Since readings of each obstacle sensor can vary substantially (successive readings may differ by several hundred or more), each sensor can be queried sampleSize times and an average obtained.

Parameters
obstSensorsarray to store intensity values
sampleSizehow many readings are taken for each sensor
Precondition
space already allocated for obstSensors array sampleSize > 0
Postcondition
obstSensors[0] gives average value for left sensor obstSensors[1] gives average value for middle sensor obstSensors[2] gives average value for right sensor Obstacle values near 0 represent no obstacle is seen Obstacle values may approach 6000 as obstacle gets close.
Warning
As battery degrades, sensor readings degrade, yielding systematically lower numbers.
int rGetObstacleTxt ( const char *  sensorName,
int  sampleSize 
)

Get the average values of a specified obstacle (IR) sensor. Since values of each obstacle sensor can vary substantially (successive readings may differ by several hundred or more), the sensor can be queried sampleSize times and an average obtained.

Parameters
sensorNamename of the obstacle sensor
Precondition
sensorName is "left", "center", "middle", or "right" (not case sensitive) designations "center" and "middle" are alternatives for the same light sensor
Parameters
sampleSizehow many readings are taken for the sensor
Precondition
space already allocated for vals array sampleSize > 0
Returns
reading from the specified obstacle sensor, averaged over sampleSize number of data samples Obstacle values near 0 represent no obstacle is seen Obstacle values may approach 6000 as obstacle gets close.
Warning
As battery degrades, sensor values degrade, yielding systematically lower numbers.
int rGetStall ( int  sampleSize)

Determine if robot has stalled Since readings of each brightness sensor can vary substantially, each sensor can be queried sampleSize times and an average obtained.

Parameters
sampleSizehow many readings are taken for each sensor
Precondition
sampleSize > 0
Returns
whether or not robot current has stalled
Postcondition
Returns 1 if the robot has stalled Returns 0 otherwise.
void rHardStop ( )

cuts power to the motor of the robot

Picture rLoadPicture ( char *  filename)

Load a picture from a .jpeg file.

Parameters
filenamethe name of the file
Precondition
file must exist
file must be a 256x192 .jpeg or .jpg
Returns
Picture
void rMotors ( double  leftSpeed,
double  rightSpeed 
)

move robot with given speeds for the left and right motors continues until given another motion command or disconnected (non-blocking)

Parameters
leftSpeedthe rate at which the left wheel should turn linear range: -1.0 specifies move backward at full speed 0.0 specifies no forward/backward movement 1.0 specifies move forwardward at full speed
rightSpeedthe rate at which the right wheel should turn linear range: -1.0 specifies move backward at full speed 0.0 specifies no forward/backward movement 1.0 specifies move forward at full speed
void rSavePicture ( Picture  pic,
char *  filename 
)

Save a Picture to a .jpeg.

Parameters
picRGB picture struct from Scribbler 2 camera
filenamethe name of the file
Precondition
filename ends with .jpeg or .jpg.
Postcondition
If the file does not exist, a new file will be created.
If the file exists, the file will be overwritten.
void rSetConnection ( int  socket_num)

set current connection to the socket number

Parameters
socket_numthe number of an open socket for communication
Precondition
socket_num has been returned by rConnect the designated socket has not been closed
void rSetForwardness ( char *  direction)

specifies which end of the Scribbler is considered the front

Parameters
directionidentifies front direction
Precondition
direction is either "fluke-forward" or "scribbler-forward" (not case sensitive)
void rSetForwardnessTxt ( char *  direction)

alternative to rSetForwardness for compatibility with earlier MyroC

void rSetIRPower ( int  power)

Set the amount of power for the dongle's IR sensors.

Parameters
powerthe desired power level for the IR sensors
Precondition
power is between 0 and 255 (inclusive)
void rSetLEDBack ( double  led)

Set the the intensity of the back fluke LED,.

Parameters
ledintensity of the LED values between 0 and 1 provide a range of brightness from off to full intensity values bigger than 1 are treated as 1 (full brightness) values less than 0 are treated as 0 (LED off).
void rSetLEDFront ( int  led)

Set the front [fluke] LED on or off.

Parameters
ledvalue 1 turns on LED value 0 turns off LED
Precondition
led must be 0 or 1
void rSetName ( const char *  name)

Change name stored in the robot to the 16-byte name given.

Parameters
namespecifies new name of robot if < 16 bytes given, name is filled with null characters if >= 16 bytes given, name is truncated to 15 bytes plus null
void rStop ( )

directs robot to stop movement

Picture rTakePicture ( )

Use the camera to take a photo.

Returns
Picture
void rTurnLeft ( double  speed,
double  time 
)

turn Scribbler left for a specified time and speed

Parameters
speedthe rate at which the robot should move left linear range: -1.0 specifies right turn at full speed 0.0 specifies no turn 1.0 specifies left turn at full speed
timespecifies the duration of the turn if negative: robot continues to turn until given another motion command or disconnected (non-blocking) if nonnegative: robot turns for the given duration, in seconds
void rTurnRight ( double  speed,
double  time 
)

turn Scribbler right for a specified time and speed

Parameters
speedthe rate at which the robot should move right linear range: -1.0 specifies left turn at full speed 0.0 specifies no turn 1.0 specifies right turn at full speed
timespecifies the duration of the turn if negative: robot continues to turn until given another motion command or disconnected (non-blocking) if nonnegative: robot turns for the given duration, in seconds
void rTurnSpeed ( char *  direction,
double  speed,
double  time 
)

turn Scribbler in direction for a specified time and speed

Parameters
directiondirection of turn, based on looking from the center of the robot and facing forward
speedthe rate at which the robot should move forward linear range: -1.0 specifies turn at full speed 0.0 specifies no turn 1.0 specifies turn at full speed
timespecifies the duration of the turn if negative: robot continues to turn until given another motion command or disconnected if nonnegative: robot turns for the given duration, in seconds
Precondition
direction is "left" or "right"