Jwatson: /* sendI2CMsg */

2012-09-06T14:31:07Z

sendI2CMsg

Bfeher: Created page with "NXT|NXT {| class="wikiText" |- |''For ROBOTC NXT Sensor ''functions'', check out the [[NXT_Functions_Sensors|NXT Sens..."

2012-04-18T20:24:39Z

Created page with "<yambe:breadcrumb self="I2C Sensors">NXT|NXT</yambe:breadcrumb> {| class="wikiText" |- |''For ROBOTC NXT Sensor ''functions'', check out the [[NXT_Functions_Sensors|NXT Sens..."

New page

<yambe:breadcrumb self="I2C Sensors">NXT|NXT</yambe:breadcrumb>

{| class="wikiText"
|-
|''For ROBOTC NXT Sensor ''functions'', check out the [[NXT_Functions_Sensors|NXT Sensor Functions]] page!''

''For more examples and explanations, head over to [[NXT_Sensors_Overview|NXT Sensors Overview]] page!''
|-
|}

{{tl|1|1}}

== Information ==
{| class="wikiText"
|-
|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 ==
{| style="color:black;" width="100%" cellpadding="5%" cellspacing="0" border="0"
|-
| class="variableType"| word nI2CBytesReady[tSensors sensor]
|-
| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;"|([[Data_Types#dataType_word|word]]) Number of queued bytes ready for access from previous I2C read requests.
|-
|
{| class="parameterTable" cellpadding="5%" width="100%"
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Parameter
! width="60%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Explanation
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Data Type
|-
| style="border-style: solid; border-width: 1px 0px 0px 0px"|''sensor''
| style="border-style: solid; border-width: 1px 0px 0px 0px"|A sensor port or name
| style="border-style: solid; border-width: 1px 0px 0px 0px"|[[Data_Types#dataType_tSensors|tSensors]]
|-
|}
|-
|
{|
|-
|<syntaxhighlight lang="robotc">
nI2CBytesReady[i2cScanPort] = 0; // queue no bytes.
</syntaxhighlight>
|-
|}
|-
|}
 

== nI2CRetries ==
{| style="color:black;" width="100%" cellpadding="5%" cellspacing="0" border="0"
|-
| class="variableType"| word nI2CRetries
|-
| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;"|([[Data_Types#dataType_word|word]]) The number of re-transmission attempts that should be made for I2C message.
|-
|
{|
|-
|<syntaxhighlight lang="robotc">
nI2CRetries = 0; // do or do not, there is no try
</syntaxhighlight>
|-
|}
|-
|}
 

== nI2CStatus ==
{| style="color:black;" width="100%" cellpadding="5%" cellspacing="0" border="0"
|-
| class="variableType"| TI2CStatus nI2CStatus[tSensors sensor]
|-
| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;"|([[Data_Types#dataType_TI2CStatus|TI2CStatus]]) Current status of an sensor I2C link.
|-
|
{| class="parameterTable" cellpadding="5%" width="100%"
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Parameter
! width="60%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Explanation
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Data Type
|-
| style="border-style: solid; border-width: 1px 0px 0px 0px"|''sensor''
| style="border-style: solid; border-width: 1px 0px 0px 0px"|A sensor port or name
| style="border-style: solid; border-width: 1px 0px 0px 0px"|[[Data_Types#dataType_tSensors|tSensors]]
|-
|}
|-
|
{|
|-
|<syntaxhighlight lang="robotc">
#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;
}
</syntaxhighlight>
|-
|}
|-
|}
 

== readI2CReply ==
{| style="color:black;" width="100%" cellpadding="5%" cellspacing="0" border="0"
|-
| class="functionType"| void readI2CReply(const tSensors nPort, byte &replyBytes, const int nBytesToRead)
|-
| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;"|([[Data_Types#dataType_void|void]]) Retrieve the reply bytes from an I2C message.
|-
|
{| class="parameterTable" cellpadding="5%" width="100%"
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Parameter
! width="60%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Explanation
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Data Type
|-
| style="border-style: solid; border-width: 1px 0px 0px 0px"|''nPort''
| style="border-style: solid; border-width: 1px 0px 0px 0px"|A sensor port or name
| style="border-style: solid; border-width: 1px 0px 0px 0px"|[[Data_Types#dataType_tSensors|tSensors]]
|-
| style="border-style: solid; border-width: 0px 0px 0px 0px"|''replyBytes''
| style="border-style: solid; border-width: 0px 0px 0px 0px"|Where to save the message
| style="border-style: solid; border-width: 0px 0px 0px 0px"|[[Data_Types#dataType_byte|byte]]
|-
| style="border-style: solid; border-width: 0px 0px 0px 0px"|''nBytesToRead''
| style="border-style: solid; border-width: 0px 0px 0px 0px"|How many bytes to read from message
| style="border-style: solid; border-width: 0px 0px 0px 0px"|[[Data_Types#dataType_int|int]]
|-
|}
|-
|
{|
|-
|<syntaxhighlight lang="robotc">
#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;
}
</syntaxhighlight>
|-
|}
|-
|}

== sendI2CMsg ==
{| style="color:black;" width="100%" cellpadding="5%" cellspacing="0" border="0"
|-
| class="functionType"| void sendI2CMsg(const tSensors nPort, const byte &sendMsg, const int nReplySize)
|-
| style="font-family:Verdana, Geneva, sans-serif; color:black; background-color:#FFFFFF; text-align:left; font-size:100%;"|([[Data_Types#dataType_void|void]]) Send an I2C message on the specified sensor port.
|-
|
{| class="parameterTable" cellpadding="5%" width="100%"
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Parameter
! width="60%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Explanation
! width="20%" style="border-style: solid; border-width: 0px 0px 1px 0px"|Data Type
|-
| style="border-style: solid; border-width: 1px 0px 0px 0px"|''nPort''
| style="border-style: solid; border-width: 1px 0px 0px 0px"|A sensor port or name
| style="border-style: solid; border-width: 1px 0px 0px 0px"|[[Data_Types#dataType_tSensors|tSensors]]
|-
| style="border-style: solid; border-width: 0px 0px 0px 0px"|''sendMsg''
| style="border-style: solid; border-width: 0px 0px 0px 0px"|The message to send
| style="border-style: solid; border-width: 0px 0px 0px 0px"|[[Data_Types#dataType_byte|byte]]
|-
| style="border-style: solid; border-width: 0px 0px 0px 0px"|''nReplySize''
| style="border-style: solid; border-width: 0px 0px 0px 0px"|The size of the message being sent
| style="border-style: solid; border-width: 0px 0px 0px 0px"|[[Data_Types#dataType_int|int]]
|-
|}
|-
|
{|
|-
|<syntaxhighlight lang="robotc">
sendI2CMsg(i2cScanPort, i2cScanDeviceMsg[0], 8); // send an 8 byte message from
// 'i2cScanDeviceMsg[0]' to 'i2cScanPort' (S1)
</syntaxhighlight>
|-
|}
|-
|}

@@ Line 215: / Line 215: @@
    |-
    | style="border-style: solid; border-width: 0px 0px 0px 0px"|''nReplySize''
-   | style="border-style: solid; border-width: 0px 0px 0px 0px"|The size of the message being sent
+   | style="border-style: solid; border-width: 0px 0px 0px 0px"|Specifies the length, in bytes, of the reply expected from the sensor.
    | style="border-style: solid; border-width: 0px 0px 0px 0px"|[[Data_Types#dataType_int|int]]
    |-
@@ Line 224: / Line 224: @@
    |-
    |<syntaxhighlight lang="robotc">
-sendI2CMsg(i2cScanPort, i2cScanDeviceMsg[0], 8);  // send an 8 byte message from
+sendI2CMsg(i2cScanPort, i2cScanDeviceMsg[0], 8);  // send a message from 'i2cScanDeviceMsg[0]' to
-                                                  // 'i2cScanDeviceMsg[0]' to 'i2cScanPort' (S1)
+                                                  //'i2cScanPort' (S1), expecting an 8 byte return message
 </syntaxhighlight>
    |-

NXT I2C Sensors - Revision history

Jwatson: /* sendI2CMsg */

Bfeher: Created page with "NXT|NXT {| class="wikiText" |- |''For ROBOTC NXT Sensor ''functions'', check out the [[NXT_Functions_Sensors|NXT Sens..."