LeJOS OSEK C++ Library v0.4

API

Robert W. Kramer, Youngstown State University

 

Disclaimer

The Lejos OSEK C++ library and this document are © 2008 by Robert W. Kramer, and are made available subject to the Mozilla Public License, version 1.0. You may obtain a copy of the license at http://www.mozilla.org/MPL/.

 

Discussion

The LeJOS OSEK C++ library provides a set of classes which provide abstractions for the motors and sensors used with the Lego Mindstorms NXT, as well as modifications to the LeJOS OSEK software to allow C++ programs to compile and run properly.

 

The current version of the C++ functionality (v0.4) was intended to accomplish the following:

  • Proof-of-concept: Yes, we can write our code in C++, compile it and run it natively on the NXT’s ARM7 processor.
  • Explore limitations: Classes, objects, templates have all worked pretty much error-free in early testing. Exceptions should work, but haven’t been very well tested yet.
  • Basic class library: Classes were created for the motors and sensors in the author’s personal NXT collection. The methods are chosen and named to closely match their LeJOS counterparts.
  • Personal: The author needed a means for programming the NXT in C++, preferably natively rather than via remote control.

 

This is the first version of the library and support code. As such, it’s likely to have bugs. Caveat emptor, your mileage may vary, and all of the standard disclaimers and clichés apply.

 

If you encounter a bug, please send email describing the bug to the author at snowyowl000 -at- gmail -dot- com.

 

Known issues:

  • Exceptions and static local objects should work, but haven’t been tested well enough for my comfort.
  • Global objects do work, as do local objects and templates.

 

Credits

The author would like to thank the following for helping to make this project possible:

  • God, without whom none of this is possible
  • Betsy, Corinne and Kent for giving the author “play time” with his robots
  • Masaaki Mizuno, Kansas State University, for porting Toppers ATK to the ARM7 processor
  • Takashi Chikamasa, for creating the LeJOS OSEK system
  • Frank Klassner, Villanova University, Pam Lawhead, University of Mississippi, and Myles McNally, Alma College, for running the LMiCSE workshops and sparking the author’s interest in LeJOS

 

The API

 

Available classes

Class

Header

AccelSensor

AccelSensor.h

ColorSensor

ColorSensor.h

CompassSensor

CompassSensor.h

LightSensor

LightSensor.h

SonarSensor

SonarSensor.h

SoundSensor

SoundSensor.h

TouchSensor

TouchSensor.h

PrototypeSensor

PrototypeSensor.h

Motor

Motor.h

 

Available enumerations

Symbol

Value

Description

S1

0

Sensor port 1

S2

1

Sensor port 2

S3

2

Sensor port 3

S4

3

Sensor port 4

MOTOR_A

0

Motor port A

MOTOR_B

1

Motor port B

MOTOR_C

2

Motor port C

 

Notes:

  • These are available from the above headers or from LejosOSEKCC.h.

 

AccelSensor methods

Method prototype

Description

AccelSensor(unsigned char _port)

Constructor.

~AccelSensor( )

Destructor.

void activate(void)

Turn on the sensor. Supplies power to the sensor.

void passivate(void)

Turn off the sensor. Removes power from the sensor.

short int getXAccel(void)

Return acceleration along the x-axis.

short int getYAccel(void)

Return acceleration along the y-axis.

short int getZAccel(void)

Return acceleration along the z-axis.

void getAccel(short int axes[3])

Return acceleration along all three axes.

void getAccel( short int &x,
                        short int &y,

                        short int &z)

Return acceleration along all three axes.

bool isActivated(void)

Returns true iff sensor has power.

 

Notes:

  • Range is ±2g, in increments of 0.01g.
  • The positive x-axis passes through the black faceplate of the sensor.
  • The positive y-axis passes through the right side of the sensor (the side with the © symbol toward the plug).
  • The positive z-axis passes through the top (white cover) of the sensor.

 

ColorSensor methods

Method prototype

Description

ColorSensor(unsigned char _port)

Constructor.

~ColorSensor( )

Destructor.

void activate(void)

Turns on the sensor.

void passivate(void)

Turns off the sensor.

bool isActivated(void)

Returns true iff sensor has power.

unsigned char getColorNumber(void)

Returns color number.

unsigned getColorIndex(void)

Returns 6-bit value, three two-bit R/G/B levels.

void getColor(unsigned short rgb[3])

Get color data.

void getColor( short int &r,

                        short int &g,

                        short int &b)

Get color data.

short int getRed(void)

Get red level.

short int getGreen(void)

Get green level.

short int getBlue(void)

Get blue level.

void getRawColor(unsigned short rgb[3])

Get raw color data.

void getRawColor(   short int &r,

                                 short int &g,

                                 short int &b)

Get raw color data.

short int getRawRed(void)

Get raw red level.

short int getRawGreen(void)

Get raw green level.

short int getRawBlue(void)

Get raw blue level.

void getNormalizedColor(unsigned short rgb[3])

Get normalized color data.

void getNormalizedColor(short int &r,

                                          short int &g,

                                          short int &b)

Get normalized color data.

short int getNormalizedRed(void)

Get normalized red level.

short int getNormalizedGreen(void)

Get normalized green level.

short int getNormalizedBlue(void)

Get normalized blue level.

 

Notes:

  • Color values are in the 0 – 255 range.
  • Raw values are in the 0 – 1023 range.
  • Normalized values adjust the brightest RGB component to 255 and scale the other components accordingly.
  • See the HiTechnic documentation at http://www.hitechnic.com/contents/media/Color%20Number.jpg for a list of color numbers.

 

CompassSensor methods

Method prototype

Description

CompassSensor(unsigned char _port)

Constructor.

~CompassSensor( )

Destructor.

void activate(void)

Turn on sensor.

void passivate(void)

Turn off sensor.

bool isActivated(void)

Returns true iff sensor has power.

short int getHeading(void)

Returns direction in degrees.

void beginCalibration(void)

Puts sensor in calibration mode.

bool endCalibration(void)

Puts sensor in normal mode. Returns true iff calibration was successful.

 

Notes:

 

LightSensor methods

Method prototype

Description

LightSensor( unsigned char _port,bool _lamp=true)

Constructor. Turns on lamp by default.

~LightSensor( )

Destructor.

void setLamp(bool _lamp)

Turns on sensor lamp iff _lamp is true.

bool isLit(void)

Returns true iff sensor has power.

short int getValue(void)

Returns light level.

short int getRawValue(void)

Returns raw light level.

 

Notes:

  • Light values are in the range 0 – 100.
  • Raw values are in the range 0 – 1023.

 

SonarSensor methods

Method prototype

Description

SonarSensor(unsigned char _port)

Constructor.

~SonarSensor( )

Destructor.

void activate(void)

Turn on the sensor.

void passivate(void)

Turn off the sensor.

bool isActivated(void)

Returns true iff sensor has power.

short int getDistance(void)

Returns distance to closest object in sensor’s field of view.

 

Notes:

 

SoundSensor methods

Method prototype

Description

SoundSensor(unsigned char _port,bool _dba=false)

Constructor. Turns off dBA mode by default.

~SoundSensor( )

Destructor.

bool isDBA(void)

Returns true iff sensor is in dBA mode.

short int getValue(void)

Returns sound level.

short int getRawValue(void)

Return raw sound level.

 

Notes:

  • dBA mode is more sensitive to sounds in the range of normal human speech.
  • Sound levels are in the range 0 – 100.
  • Raw sound levels are in the range 0 – 1023.

 

TouchSensor methods

Method prototype

Description

TouchSensor(unsigned char _port)

Constructor.

~TouchSensor( )

Destructor.

bool isPressed(void)

Returns true iff sensor is pressed.

short int getRawValue(void)

Returns raw value.

 

Notes:

  • Raw values are < 512 if the sensor is pressed, >= 512 if it is not pressed.

 

PrototypeSensor methods

Method prototype

Description

PrototypeSensor(   unsigned char _port,
                              unsigned int _sample=10)

Constructor.

~PrototypeSensor( )

Destructor.

void setSampleRate(unsigned int rate)

Set sampling rate (4 ≤ rate ≤ 100).

void setDigitalPorts(unsigned char dir)

Set direction of digital ports.

void writeDigitalData(unsigned char data)

Write bits to any digital port configured for output.

unsigned char readDigitalData(void)

Read bits from any digital port configured for input.

void readAnalogData(unsigned int analogPorts[5])

Read all ADC ports.

unsigned int readAnalogData(int analogPort)

Read given ADC port.

 

Notes:

  • setSampleRate( ) forces rate to fall within the given bounds.
  • For setDigitalPorts( ), set bit p to 1 to configure port p for output, set it to 0 to configure the port for input. 0 ≤ p ≤ 5.
  • For writeDigitalData( ), set bit p to the bit to be written to port p. Bits corresponding to input ports are ignored.
  • For readDigitalData( ), bit p is set to the port’s value if port p is configured for input. Ports configured for output have their bits set to 0.

 

Motor methods

Method prototype

Description

Motor(unsigned char _port)

Constructor.

~Motor( )

Destructor.

void forward(void)

Starts motor running forward.

void backward(void)

Starts motor running backward.

void reverseDirection(void)

Reverses current motor direction.

void stop(void)

Stops motor with brake.

void flt(void)

Stops motor without brake.

int getTachoCount(void)

Returns tachometer value.

void resetTachoCount(void)

Resets tachometer value to 0.

void setPower(int _power)

Sets motor power.

 

Notes:

  • One tachometer count is approximately one degree of rotation.
  • The rotor is at the front of the motor, the plug is at the back. If the motor is oriented so that the plug is above the three axle holes in the back of the motor, then the forward( ) method will turn a wheel in the forward direction.
  • Power and speed are related, but not identical!

 

Other functions

Prototype

Description

void sleep(unsigned int duration)

Task will sleep for duration milliseconds. Task blocks, allowing other tasks to execute.

 

Notes:

  • Currently, eight tasks may sleep simultaneously. If you have a need for more, change the N_SLEEPERS constant in LejosOSEKCC.h and recompile the library.