NXT I2C Sensors

From ROBOTC API Guide
Jump to: navigation, search
NXT → I2C Sensors


For ROBOTC NXT Sensor functions, check out the NXT Sensor Functions page!

For more examples and explanations, head over to NXT Sensors Overview page!


Color Key
Function:
Variable:


Information

User programming of NXT digital sensors is for advanced users. The average user will not require this capability.


Sensors on the NXT can be either analog or digital sensors.

  • For analog sensors, one of the sensor input wires contains an analog value representing the value of the sensor.
  • Digital sensors are more intelligent and typically contain a microprocessor. The sensor communicates with the NXT using the I2C serial communications protocol.

Each of the four sensor ports on the NXT can be configured as either a digital or analog sensor. There are integrated device drivers for the LEGO developed sensors built into the ROBOTC firmware. If an application program wants to provide its own device drivers for either existing or new 3rd party sensors, it is important to set the sensor type to a “custom user provided device driver” so that there are no conflicts between the built-in device drivers and the user written code. There are four sensor types that are valid for application controlled digital sensors on a NXT. These are:

sensorI2CCustomStd
Indicates that user program sensor using standard baud rate communications. Standard communications operates at about 1 byte transferred per millisecond.
sensorI2CCustomStd9V
Same as above with the addition that battery voltage (i.e. 9V less the drop through a protection diode) is also provided on pin X for those sensors that want the higher voltage level.
sensorI2CCustomFast
Indicates that user program sensor using enhanced baud rate communications. The enhanced baud rate is about five times faster than the standard baud rate. So far, all new 3rd party sensors that have been tested are compatible with the enhanced baud rate; in testing only the LEGO Sonar sensor requires use of the standard baud rate.
sensorI2CCustomFast9V
Same as above with the addition that battery voltage (i.e. 9V less the drop through a protection diode) is also provided on pin X for those sensors that want the higher voltage level.

There are several sample programs in the ROBOTC distribution that illustrate the use of I2C messaging on the NXT with ROBOTC. There are a few things to remember in I2C messaging:

  • The reply bytes from an I2C “read” message are stored in a circular buffer until read by application program.
  • Before sending an I2C “read” message, it is good practice to clear out any reply bytes that exist in the buffer.
  • I2C messaging can be slow. There are several bytes of protocol overhead on every message.
  • In implementing a device driver, it is better to start up a task that continually sends I2C messages to periodically poll the sensor and stores the results. Within the user application it should simply retrieve the last polled value – i.e. no delay – rather than do an inline I2C read to get the sensor value. ROBOTC makes this very easy to achieve by allowing user programs to write as well as read the internal “SensorValue” array. The "SensorValue” array is used to retrieve the value of a sensor from the internal device drivers.
  • You program should accommodate and recover from the occasional I2C messaging error. Lots of testing has indicated that most sensors experience errors rates of 10^-3 to 10^-5.


nI2CBytesReady

word nI2CBytesReady[tSensors sensor]
(word) Number of queued bytes ready for access from previous I2C read requests.
Parameter Explanation Data Type
sensor A sensor port or name tSensors
nI2CBytesReady[i2cScanPort] = 0;  // queue no bytes.


nI2CRetries

word nI2CRetries
(word) The number of re-transmission attempts that should be made for I2C message.
nI2CRetries = 0;  // do or do not, there is no try


nI2CStatus

TI2CStatus nI2CStatus[tSensors sensor]
(TI2CStatus) Current status of an sensor I2C link.
Parameter Explanation Data Type
sensor A sensor port or name tSensors
#define i2cScanPort  S1             // port to Scan!
TI2CStatus nStatus;                 // status variable
byte replyMsg[10];                  // reply Message byte Array of size 10
 
nStatus = nI2CStatus[i2cScanPort];  // check the status of the port in question (S1 in this case)
if(nStatus != NO_ERR)               // if the status is not, 'NO_ERR':
{
  return false;              
}
 
readI2CReply(i2cScanPort, replyMsg[0], 8);  // retrieve 8 reply bytes from 'i2cScanPort' (S1) to 'replyMsg[0]'
if(replyMsg[0] == 0x00)                     // if the bytes are hexidecimal '0' (0x00):
{
  return false;
}


readI2CReply

void readI2CReply(const tSensors nPort, byte &replyBytes, const int nBytesToRead)
(void) Retrieve the reply bytes from an I2C message.
Parameter Explanation Data Type
nPort A sensor port or name tSensors
replyBytes Where to save the message byte
nBytesToRead How many bytes to read from message int
#define i2cScanPort  S1             // port to Scan!
TI2CStatus nStatus;                 // status variable
byte replyMsg[10];                  // reply Message byte Array of size 10
 
nStatus = nI2CStatus[i2cScanPort];  // check the status of the port in question (S1 in this case)
if(nStatus != NO_ERR)               // if the status is not, 'NO_ERR':
{
  return false;              
}
 
readI2CReply(i2cScanPort, replyMsg[0], 8);  // retrieve 8 reply bytes from 'i2cScanPort' (S1) to 'replyMsg[0]'
if(replyMsg[0] == 0x00)                     // if the bytes are hexidecimal '0' (0x00):
{
  return false;
}


sendI2CMsg

void sendI2CMsg(const tSensors nPort, const byte &sendMsg, const int nReplySize)
(void) Send an I2C message on the specified sensor port.
Parameter Explanation Data Type
nPort A sensor port or name tSensors
sendMsg The message to send byte
nReplySize Specifies the length, in bytes, of the reply expected from the sensor. int
sendI2CMsg(i2cScanPort, i2cScanDeviceMsg[0], 8);  // send a message from 'i2cScanDeviceMsg[0]' to 
                                                  //'i2cScanPort' (S1), expecting an 8 byte return message