nbc_guide

NBCVersion 1.2.1 r5

Generated by Doxygen 1.6.2

Mon Oct 17 09:52:27 2011

CONTENTS i

Contents

1 NBC Programmers Guide 1

2 Introduction 2

3 The NBC Language 2

3.1 Lexical Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3.1.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3.1.2 Whitespace . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3.1.3 Numerical Constants . . . . . . . . . . . . . . . . . . . . . . 4

3.1.4 String Constants . . . . . . . . . . . . . . . . . . . . . . . . 4

3.1.5 Identifiers and Keywords . . . . . . . . . . . . . . . . . . . . 5

3.2 Program Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2.1 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2.2 Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.2.3 Macro Functions . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2.4 Data Segments . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.3 The Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.3.1 #include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.3.2 #define . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.3.3 ## (Concatenation) . . . . . . . . . . . . . . . . . . . . . . . 18

3.3.4 Conditional Compilation . . . . . . . . . . . . . . . . . . . . 19

3.3.5 #import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.3.6 #download . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.4 Compiler Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.5 Expression Evaluator . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.6 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.6.1 Assignment Statements . . . . . . . . . . . . . . . . . . . . . 23

3.6.2 Math Statements . . . . . . . . . . . . . . . . . . . . . . . . 24

3.6.3 Logic Statements . . . . . . . . . . . . . . . . . . . . . . . . 34

3.6.4 Bit Manipulation Statements . . . . . . . . . . . . . . . . . . 36

Generated on Mon Oct 17 09:52:27 2011 for NBC by Doxygen

CONTENTS ii

3.6.5 Comparison Statements . . . . . . . . . . . . . . . . . . . . 38

3.6.6 Control Flow Statements . . . . . . . . . . . . . . . . . . . . 39

3.6.7 syscall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.6.8 Timing Statements . . . . . . . . . . . . . . . . . . . . . . . 58

3.6.9 Array Statements . . . . . . . . . . . . . . . . . . . . . . . . 59

3.6.10 String Statements . . . . . . . . . . . . . . . . . . . . . . . . 62

3.6.11 Scheduling Statements . . . . . . . . . . . . . . . . . . . . . 65

3.6.12 Input Statements . . . . . . . . . . . . . . . . . . . . . . . . 68

3.6.13 Output Statements . . . . . . . . . . . . . . . . . . . . . . . 69

3.6.14 Compile-time Statements . . . . . . . . . . . . . . . . . . . . 70

4 TXGPacket 73

5 Module Documentation 73

5.1 Comparison Constants . . . . . . . . . . . . . . . . . . . . . . . . . 73

5.1.1 Detailed Description . . . . . . . . . . . . . . . . . . . . . . 73

5.1.2 Define Documentation . . . . . . . . . . . . . . . . . . . . . 73

5.2 NXT Firmware Modules . . . . . . . . . . . . . . . . . . . . . . . . 74


5.3 Input module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75


5.4 Input module constants . . . . . . . . . . . . . . . . . . . . . . . . . 76



5.5 Sensor types and modes . . . . . . . . . . . . . . . . . . . . . . . . . 77


5.6 Output module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79


5.7 Output module constants . . . . . . . . . . . . . . . . . . . . . . . . 79


5.8 Command module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80



CONTENTS iii

5.9 Command module constants . . . . . . . . . . . . . . . . . . . . . . 81



5.10 Comm module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83


5.11 Button module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84


5.12 IOCtrl module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84


5.13 Loader module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84


5.14 Sound module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85


5.15 Ui module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86


5.16 Low Speed module . . . . . . . . . . . . . . . . . . . . . . . . . . . 86


5.17 Display module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88


5.18 HiTechnic API Functions . . . . . . . . . . . . . . . . . . . . . . . . 88



5.19 SuperPro analog output mode constants . . . . . . . . . . . . . . . . 142



5.20 SuperPro LED control constants . . . . . . . . . . . . . . . . . . . . 144



5.21 SuperPro digital pin constants . . . . . . . . . . . . . . . . . . . . . 145




CONTENTS iv

5.22 SuperPro Strobe control constants . . . . . . . . . . . . . . . . . . . 146



5.23 MindSensors API Functions . . . . . . . . . . . . . . . . . . . . . . 147



5.24 Codatex API Functions . . . . . . . . . . . . . . . . . . . . . . . . . 236



5.25 Dexter Industries API Functions . . . . . . . . . . . . . . . . . . . . 239



5.26 Microinfinity API Functions . . . . . . . . . . . . . . . . . . . . . . 251



5.27 RIC Macro Wrappers . . . . . . . . . . . . . . . . . . . . . . . . . . 253



5.28 NXT firmware module names . . . . . . . . . . . . . . . . . . . . . 261



5.29 NXT firmware module IDs . . . . . . . . . . . . . . . . . . . . . . . 263



5.30 Miscellaneous NBC/NXC constants . . . . . . . . . . . . . . . . . . 265



5.31 Third-party NXT devices . . . . . . . . . . . . . . . . . . . . . . . . 266


5.32 Standard-C API functions . . . . . . . . . . . . . . . . . . . . . . . . 267



CONTENTS v

5.33 A simple 3D graphics library . . . . . . . . . . . . . . . . . . . . . . 268



5.34 Output module functions . . . . . . . . . . . . . . . . . . . . . . . . 276



5.35 Input module functions . . . . . . . . . . . . . . . . . . . . . . . . . 296



5.36 LowSpeed module functions . . . . . . . . . . . . . . . . . . . . . . 313



5.37 Low level LowSpeed module functions . . . . . . . . . . . . . . . . . 324



5.38 Display module functions . . . . . . . . . . . . . . . . . . . . . . . . 329



5.39 Sound module functions . . . . . . . . . . . . . . . . . . . . . . . . 349



5.40 Command module functions . . . . . . . . . . . . . . . . . . . . . . 357



5.41 Button module functions . . . . . . . . . . . . . . . . . . . . . . . . 377



5.42 Ui module functions . . . . . . . . . . . . . . . . . . . . . . . . . . 382



5.43 Comm module functions . . . . . . . . . . . . . . . . . . . . . . . . 391


CONTENTS vi



5.44 Direct Command functions . . . . . . . . . . . . . . . . . . . . . . . 433



5.45 System Command functions . . . . . . . . . . . . . . . . . . . . . . 447



5.46 IOCtrl module functions . . . . . . . . . . . . . . . . . . . . . . . . 461



5.47 Loader module functions . . . . . . . . . . . . . . . . . . . . . . . . 461



5.48 cstdlib API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473



5.49 cmath API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474



5.50 Property constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475



5.51 Array operation constants . . . . . . . . . . . . . . . . . . . . . . . . 476



5.52 System Call function constants . . . . . . . . . . . . . . . . . . . . . 477



5.53 Line number constants . . . . . . . . . . . . . . . . . . . . . . . . . 486



CONTENTS vii


5.54 Time constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488



5.55 Mailbox constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494



5.56 VM state constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 496



5.57 Fatal errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497



5.58 General errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499



5.59 Communications specific errors . . . . . . . . . . . . . . . . . . . . 500



5.60 Remote control (direct commands) errors . . . . . . . . . . . . . . . 501



5.61 Program status constants . . . . . . . . . . . . . . . . . . . . . . . . 502



5.62 Command module IOMAP offsets . . . . . . . . . . . . . . . . . . . 503



5.63 IOCtrl module constants . . . . . . . . . . . . . . . . . . . . . . . . 505


5.64 PowerOn constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 505


CONTENTS viii



5.65 IOCtrl module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . 506



5.66 Loader module constants . . . . . . . . . . . . . . . . . . . . . . . . 507



5.67 Loader module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . 507



5.68 Loader module error codes . . . . . . . . . . . . . . . . . . . . . . . 508



5.69 Loader module function constants . . . . . . . . . . . . . . . . . . . 512



5.70 Sound module constants . . . . . . . . . . . . . . . . . . . . . . . . 516


5.71 SoundFlags constants . . . . . . . . . . . . . . . . . . . . . . . . . . 517



5.72 SoundState constants . . . . . . . . . . . . . . . . . . . . . . . . . . 518



5.73 SoundMode constants . . . . . . . . . . . . . . . . . . . . . . . . . . 519



5.74 Sound module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . 520




CONTENTS ix

5.75 Sound module miscellaneous constants . . . . . . . . . . . . . . . . . 521



5.76 Tone constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522



5.77 Button module constants . . . . . . . . . . . . . . . . . . . . . . . . 529


5.78 Button name constants . . . . . . . . . . . . . . . . . . . . . . . . . 529



5.79 ButtonState constants . . . . . . . . . . . . . . . . . . . . . . . . . . 531



5.80 Button module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . 532



5.81 Ui module constants . . . . . . . . . . . . . . . . . . . . . . . . . . 533


5.82 CommandFlags constants . . . . . . . . . . . . . . . . . . . . . . . . 534



5.83 UIState constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535



5.84 UIButton constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 538



5.85 BluetoothState constants . . . . . . . . . . . . . . . . . . . . . . . . 539




CONTENTS x

5.86 VM run state constants . . . . . . . . . . . . . . . . . . . . . . . . . 540



5.87 Ui module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . . . 541



5.88 NBC Input port constants . . . . . . . . . . . . . . . . . . . . . . . . 543



5.89 NBC sensor type constants . . . . . . . . . . . . . . . . . . . . . . . 544



5.90 NBC sensor mode constants . . . . . . . . . . . . . . . . . . . . . . 547



5.91 Input field constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 549



5.92 Input port digital pin constants . . . . . . . . . . . . . . . . . . . . . 550



5.93 Color sensor array indices . . . . . . . . . . . . . . . . . . . . . . . 551



5.94 Color values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552



5.95 Color calibration state constants . . . . . . . . . . . . . . . . . . . . 553



5.96 Color calibration constants . . . . . . . . . . . . . . . . . . . . . . . 554


CONTENTS xi



5.97 Input module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . . 555



5.98 Constants to use with the Input modules Pin function . . . . . . . . . 557



5.99 Output port constants . . . . . . . . . . . . . . . . . . . . . . . . . . 559



5.100PID constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560



5.101Output port update flag constants . . . . . . . . . . . . . . . . . . . . 562



5.102Tachometer counter reset flags . . . . . . . . . . . . . . . . . . . . . 563



5.103Output port mode constants . . . . . . . . . . . . . . . . . . . . . . . 564



5.104Output port option constants . . . . . . . . . . . . . . . . . . . . . . 565



5.105Output regulation option constants . . . . . . . . . . . . . . . . . . . 566



5.106Output port run state constants . . . . . . . . . . . . . . . . . . . . . 566



CONTENTS xii


5.107Output port regulation mode constants . . . . . . . . . . . . . . . . . 568



5.108Output field constants . . . . . . . . . . . . . . . . . . . . . . . . . . 569



5.109Output module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . 575



5.110LowSpeed module constants . . . . . . . . . . . . . . . . . . . . . . 578


5.111LSState constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579



5.112LSChannelState constants . . . . . . . . . . . . . . . . . . . . . . . 580



5.113LSMode constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 581



5.114LSErrorType constants . . . . . . . . . . . . . . . . . . . . . . . . . 582



5.115Low speed module IOMAP offsets . . . . . . . . . . . . . . . . . . . 583



5.116LSNoRestartOnRead constants . . . . . . . . . . . . . . . . . . . . . 585



5.117Standard I2C constants . . . . . . . . . . . . . . . . . . . . . . . . . 587


CONTENTS xiii



5.118LEGO I2C address constants . . . . . . . . . . . . . . . . . . . . . . 588



5.119Ultrasonic sensor constants . . . . . . . . . . . . . . . . . . . . . . . 588



5.120LEGO temperature sensor constants . . . . . . . . . . . . . . . . . . 590



5.121E-Meter sensor constants . . . . . . . . . . . . . . . . . . . . . . . . 593



5.122I2C option constants . . . . . . . . . . . . . . . . . . . . . . . . . . 594



5.123Display module constants . . . . . . . . . . . . . . . . . . . . . . . . 595



5.124DisplayExecuteFunction constants . . . . . . . . . . . . . . . . . . . 601



5.125Drawing option constants . . . . . . . . . . . . . . . . . . . . . . . . 602



5.126Font drawing option constants . . . . . . . . . . . . . . . . . . . . . 605



5.127Display flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606



CONTENTS xiv


5.128Display contrast constants . . . . . . . . . . . . . . . . . . . . . . . 607



5.129Text line constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 608



5.130Display module IOMAP offsets . . . . . . . . . . . . . . . . . . . . 610



5.131Comm module constants . . . . . . . . . . . . . . . . . . . . . . . . 612


5.132Miscellaneous Comm module constants . . . . . . . . . . . . . . . . 614



5.133Bluetooth State constants . . . . . . . . . . . . . . . . . . . . . . . . 616



5.134Data mode constants . . . . . . . . . . . . . . . . . . . . . . . . . . 617



5.135Bluetooth state status constants . . . . . . . . . . . . . . . . . . . . . 618



5.136Remote connection constants . . . . . . . . . . . . . . . . . . . . . . 619



5.137Bluetooth hardware status constants . . . . . . . . . . . . . . . . . . 621



5.138Hi-speed port constants . . . . . . . . . . . . . . . . . . . . . . . . . 621


CONTENTS xv


5.139Hi-speed port flags constants . . . . . . . . . . . . . . . . . . . . . . 622



5.140Hi-speed port state constants . . . . . . . . . . . . . . . . . . . . . . 623



5.141Hi-speed port SysCommHSControl constants . . . . . . . . . . . . . 624



5.142Hi-speed port baud rate constants . . . . . . . . . . . . . . . . . . . . 625



5.143Hi-speed port UART mode constants . . . . . . . . . . . . . . . . . . 627



5.144Hi-speed port data bits constants . . . . . . . . . . . . . . . . . . . . 628



5.145Hi-speed port stop bits constants . . . . . . . . . . . . . . . . . . . . 629



5.146Hi-speed port parity constants . . . . . . . . . . . . . . . . . . . . . 630



5.147Hi-speed port combined UART constants . . . . . . . . . . . . . . . 631



5.148Hi-speed port address constants . . . . . . . . . . . . . . . . . . . . . 632




CONTENTS xvi

5.149Device status constants . . . . . . . . . . . . . . . . . . . . . . . . . 633



5.150Comm module interface function constants . . . . . . . . . . . . . . 634



5.151Comm module status code constants . . . . . . . . . . . . . . . . . . 637



5.152Comm module IOMAP offsets . . . . . . . . . . . . . . . . . . . . . 638



5.153RCX constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645


5.154RCX output constants . . . . . . . . . . . . . . . . . . . . . . . . . . 646



5.155RCX output mode constants . . . . . . . . . . . . . . . . . . . . . . 647



5.156RCX output direction constants . . . . . . . . . . . . . . . . . . . . . 648



5.157RCX output power constants . . . . . . . . . . . . . . . . . . . . . . 648



5.158RCX IR remote constants . . . . . . . . . . . . . . . . . . . . . . . . 649



5.159RCX and Scout sound constants . . . . . . . . . . . . . . . . . . . . 651



CONTENTS xvii


5.160Scout constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653


5.161Scout light constants . . . . . . . . . . . . . . . . . . . . . . . . . . 653



5.162Scout sound constants . . . . . . . . . . . . . . . . . . . . . . . . . . 654



5.163Scout sound set constants . . . . . . . . . . . . . . . . . . . . . . . . 657



5.164Scout mode constants . . . . . . . . . . . . . . . . . . . . . . . . . . 658



5.165Scout motion rule constants . . . . . . . . . . . . . . . . . . . . . . . 659



5.166Scout touch rule constants . . . . . . . . . . . . . . . . . . . . . . . 660



5.167Scout light rule constants . . . . . . . . . . . . . . . . . . . . . . . . 661



5.168Scout transmit rule constants . . . . . . . . . . . . . . . . . . . . . . 662



5.169Scout special effect constants . . . . . . . . . . . . . . . . . . . . . . 663



5.170RCX and Scout source constants . . . . . . . . . . . . . . . . . . . . 664


CONTENTS xviii



5.171RCX and Scout opcode constants . . . . . . . . . . . . . . . . . . . . 669



5.172HiTechnic/mindsensors Power Function/IR Train constants . . . . . . 679


5.173Power Function command constants . . . . . . . . . . . . . . . . . . 680



5.174Power Function channel constants . . . . . . . . . . . . . . . . . . . 681



5.175Power Function mode constants . . . . . . . . . . . . . . . . . . . . 681



5.176PF/IR Train function constants . . . . . . . . . . . . . . . . . . . . . 683



5.177IR Train channel constants . . . . . . . . . . . . . . . . . . . . . . . 683



5.178Power Function output constants . . . . . . . . . . . . . . . . . . . . 684



5.179Power Function pin constants . . . . . . . . . . . . . . . . . . . . . . 685



5.180Power Function single pin function constants . . . . . . . . . . . . . 685




CONTENTS xix

5.181Power Function CST options constants . . . . . . . . . . . . . . . . . 686



5.182Power Function PWM option constants . . . . . . . . . . . . . . . . 688



5.183HiTechnic device constants . . . . . . . . . . . . . . . . . . . . . . . 690



5.184HiTechnic IRSeeker2 constants . . . . . . . . . . . . . . . . . . . . . 692



5.185HiTechnic IRReceiver constants . . . . . . . . . . . . . . . . . . . . 695



5.186HiTechnic Color2 constants . . . . . . . . . . . . . . . . . . . . . . . 696



5.187HiTechnic Angle sensor constants . . . . . . . . . . . . . . . . . . . 698



5.188HiTechnic Barometric sensor constants . . . . . . . . . . . . . . . . . 700



5.189HiTechnic Prototype board constants . . . . . . . . . . . . . . . . . . 700



5.190HiTechnic Prototype board analog input constants . . . . . . . . . . . 702



5.191HiTechnic SuperPro constants . . . . . . . . . . . . . . . . . . . . . 703


CONTENTS xx



5.192HiTechnic SuperPro analog input index constants . . . . . . . . . . . 710



5.193HiTechnic SuperPro analog output index constants . . . . . . . . . . 711



5.194MindSensors device constants . . . . . . . . . . . . . . . . . . . . . 712



5.195MindSensors DIST-Nx constants . . . . . . . . . . . . . . . . . . . . 715



5.196MindSensors PSP-Nx constants . . . . . . . . . . . . . . . . . . . . 717



5.197MindSensors PSP-Nx button set 1 constants . . . . . . . . . . . . . . 719



5.198MindSensors PSP-Nx button set 2 constants . . . . . . . . . . . . . . 720



5.199MindSensors nRLink constants . . . . . . . . . . . . . . . . . . . . . 722



5.200MindSensors ACCL-Nx constants . . . . . . . . . . . . . . . . . . . 724



5.201MindSensors ACCL-Nx sensitivity level constants . . . . . . . . . . . 726



CONTENTS xxi


5.202MindSensors PFMate constants . . . . . . . . . . . . . . . . . . . . . 727



5.203PFMate motor constants . . . . . . . . . . . . . . . . . . . . . . . . 729



5.204PFMate channel constants . . . . . . . . . . . . . . . . . . . . . . . 730



5.205MindSensors NXTServo constants . . . . . . . . . . . . . . . . . . . 730


5.206MindSensors NXTServo registers . . . . . . . . . . . . . . . . . . . 731



5.207MindSensors NXTServo position constants . . . . . . . . . . . . . . 735



5.208MindSensors NXTServo quick position constants . . . . . . . . . . . 736



5.209MindSensors NXTServo servo numbers . . . . . . . . . . . . . . . . 736



5.210MindSensors NXTServo commands . . . . . . . . . . . . . . . . . . 738



5.211MindSensors NXTHID constants . . . . . . . . . . . . . . . . . . . . 739


5.212MindSensors NXTHID registers . . . . . . . . . . . . . . . . . . . . 740



CONTENTS xxii


5.213MindSensors NXTHID modifier keys . . . . . . . . . . . . . . . . . 741



5.214MindSensors NXTHID commands . . . . . . . . . . . . . . . . . . . 742



5.215MindSensors NXTPowerMeter constants . . . . . . . . . . . . . . . 743


5.216MindSensors NXTPowerMeter registers . . . . . . . . . . . . . . . . 743



5.217MindSensors NXTPowerMeter commands . . . . . . . . . . . . . . . 745



5.218MindSensors NXTSumoEyes constants . . . . . . . . . . . . . . . . 746



5.219MindSensors NXTLineLeader constants . . . . . . . . . . . . . . . . 747


5.220MindSensors NXTLineLeader registers . . . . . . . . . . . . . . . . 747



5.221MindSensors NXTLineLeader commands . . . . . . . . . . . . . . . 749



5.222Codatex device constants . . . . . . . . . . . . . . . . . . . . . . . . 751


5.223Codatex RFID sensor constants . . . . . . . . . . . . . . . . . . . . . 751




CONTENTS xxiii

5.224Codatex RFID sensor modes . . . . . . . . . . . . . . . . . . . . . . 752



5.225Dexter Industries device constants . . . . . . . . . . . . . . . . . . . 753


5.226Dexter Industries GPS sensor constants . . . . . . . . . . . . . . . . 754



5.227Dexter Industries IMU sensor constants . . . . . . . . . . . . . . . . 755



5.228Dexter Industries IMU Gyro register constants . . . . . . . . . . . . . 757



5.229Dexter Industries IMU Gyro control register 1 constants . . . . . . . . 762















5.234Dexter Industries IMU Gyro FIFO control register onstants . . . . . . 770



CONTENTS xxiv


5.235Dexter Industries IMU Gyro status register constants . . . . . . . . . 771



5.236Dexter Industries IMU Accelerometer register constants . . . . . . . . 772



5.237Dexter Industries IMU Accelerometer status register constants . . . . 776



5.238Dexter Industries IMU Accelerometer mode control register constants 777



5.239Dexter Industries IMU Accelerometer interrupt latch reset register con-stants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778



5.240Dexter Industries IMU Accelerometer control register 1 constants . . 779



5.241Dexter Industries IMU Accelerometer control register 2 constants . . 780



5.242Microinfinity device constants . . . . . . . . . . . . . . . . . . . . . 781


5.243Microinfinity CruizCore XG1300L sensor constants . . . . . . . . . . 782



5.244Microinfinity CruizCore XG1300L . . . . . . . . . . . . . . . . . . . 783




1 NBC Programmers Guide 1

5.245Data type limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784



5.246Graphics library begin modes . . . . . . . . . . . . . . . . . . . . . . 786



5.247Graphics library actions . . . . . . . . . . . . . . . . . . . . . . . . . 787



5.248Graphics library settings . . . . . . . . . . . . . . . . . . . . . . . . 789



5.249Graphics library cull mode . . . . . . . . . . . . . . . . . . . . . . . 790



6 File Documentation 790

6.1 NBCAPIDocs.h File Reference . . . . . . . . . . . . . . . . . . . . . 790


6.2 NBCCommon.h File Reference . . . . . . . . . . . . . . . . . . . . . 791



1 NBC Programmers Guide

October 10, 2011

by John Hansen

Introduction


2 Introduction 2

The NBC Language

2 Introduction

Introduction

NBC stands for NeXT Byte Codes. It is a simple language for programming the LEGOMINDSTORMS NXT product. The NXT has a byte-code interpreter (provided byLEGO), which can be used to execute programs. The NBC compiler translates a sourceprogram into LEGO NXT byte-codes, which can then be executed on the NXT itself.Although the preprocessor and format of NBC programs are similar to assembly, NBCis not a general-purpose assembly language - there are many restrictions that stem fromlimitations of the LEGO byte-code interpreter.

Logically, NBC is defined as two separate pieces. The NBC language describes thesyntax to be used in writing programs. The NBC Application Programming Inter-face (API) describes the system functions, constants, and macros that can be used byprograms. This API is defined in a special file known as a "header file" which is auto-matically included at the beginning of any NBC program.

This document describes both the NBC language and the NBC API. In short, it providesthe information needed to write NBC programs. Since there are different interfaces forNBC, this document does not describe how to use any specific NBC implementation(such as the command-line compiler or Bricx Command Center). Refer to the docu-mentation provided with the NBC tool, such as the NBC User Manual, for informationspecific to that implementation.

For up-to-date information and documentation for NBC, visit the NBC website athttp://bricxcc.sourceforge.net/nbc/.

3 The NBC Language

The NBC Language

This section describes the NBC language itself. This includes the lexical rules used bythe compiler, the structure programs, statements, and expressions, and the operation ofthe preprocessor.

Unlike some assembly languages, NBC is a case-sensitive language. That means thatthe identifier "xYz" is not the same identifier as "Xyz". Similarly, the subtract statementbegins with the keyword "sub" but "suB", "Sub", or "SUB" are all just valid identifiers- not keywords.

Lexical Rules

Program Structure


http://bricxcc.sourceforge.net/nbc/.

3.1 Lexical Rules 3

The Preprocessor

Compiler Tokens

Expression Evaluator

Statements

3.1 Lexical Rules

Lexical Rules

The lexical rules describe how NBC breaks a source file into individual tokens. Thisincludes the way comments are written, then handling of whitespace, and valid charac-ters for identifiers.

Comments

Whitespace

Numerical Constants

String Constants

Identifiers and Keywords

3.1.1 Comments

Comments

Three forms of comments are supported in NBC. The first form (traditional C com-ments) begin with / and end with /. These comments are allowed to span multiplelines, but they cannot be nested.

/* this is a comment */

/* this is a twoline comment */

/* another comment.../* trying to nest...

ending the inner comment...*/this text is no longer a comment! */

The second form of comments supported in NXBC begins with // and continues tothe end of the current line. These are sometimes known as C++ style comments.

// a single line comment

The third form of comments begins with ; and ends with a newline. This form is thetraditional assembly language style comments.


3.1 Lexical Rules 4

; another single line comment

As you might guess, the compiler ignores comments. Their only purpose is to allowthe programmer to document the source code.

3.1.2 Whitespace

Whitespace

Whitespace consists of all spaces, tabs, and newlines. It is used to separate tokens andto make a program more readable. As long as the tokens are distinguishable, adding orsubtracting whitespace has no effect on the meaning of a program. For example, thefollowing lines of code both have the same meaning:

set x,2set x, 2

Generally, whitespace is ignored outside of string constants and constant numeric ex-pressions. However, unlike in C, NBC statements may not span multiple lines. Asidefrom pre-processor macros invocations, each statement in an NBC program must beginand end on the same line.

add x, x, 2 // okayadd x, // error

x, 2 // error

set x, (2*2)+43-12 // okayset x, 2 * 2 // error (constant expression contains whitespace)

The exception to this rule is if you end a line with the \ character which makes theNBC parser continue the current statement on the next line just like with preprocessormacros.

add x, \x, 2 // okay

3.1.3 Numerical Constants

Numerical Constants

Numerical constants may be written in either decimal or hexadecimal form. Decimalconstants consist of one or more decimal digits. Decimal constants may optionallyinclude a decimal point along with one or more decimal digits following the decimalpoint. Hexadecimal constants start with 0x or 0X followed by one or more hexadecimaldigits.

set x, 10 // set x to 10set x, 0x10 // set x to 16 (10 hex)mov f, 1.5 // set f to 1.5


3.1 Lexical Rules 5

3.1.4 String Constants

String Constants

String constants in NBC are delimited with either single or double quote characters.NBC represents a string as an array of bytes, with the last byte in the array being azero. The final zero byte is generally referred to as the null terminator.

TextOut(0, LCD_LINE1, testing)

3.1.5 Identifiers and Keywords

Identifiers and Keywords

Identifiers are used for variable, task, function, and subroutine names. The first char-acter of an identifier must be an upper or lower case letter or the underscore (_).Remaining characters may be letters, numbers, and underscores.

A number of tokens are reserved for use in the NBC language itself. These are calledkeywords and may not be used as identifiers. A complete list of keywords appearsbelow:


3.2 Program Structure 6

add sub neg muldiv mod and orxor not cmp tstindex replace arrsize arrbuildarrsubset arrinit mov setflatten unflatten numtostr strtonumstrcat strsubset strtoarr arrtostrjmp brcmp brtst syscallstop exit exitto acquirerelease subcall subret setinsetout getin getout waitgettick thread endt subroutinefollows precedes segment endstypedef struct db bytesbyte ubyte dw wordsword uword dd dwordsdword udword long slongulong void mutex waitvcall return abs signstrindex strreplace strlen shlshr sizeof compchk compifcompelse compend isconstasl asr lsl lsrrotl rotr start stopthreadpriority cmnt fmtnum compchktypefloat wait2 sqrt waitvarrop acos asin atanceil exp floor tantanh cos cosh loglog10 sin sinh truncfrac atan2 pow muldivacosd asind atand tandtanhd cosd coshd sindsinhd atan2d addrof

3.2 Program Structure

Program Structure

An NBC program is composed of code blocks and global variables in data segments.There are two primary types of code blocks: thread and subroutines. Each of thesetypes of code blocks has its own unique features and restrictions, but they share acommon structure.

A third type of code block is the preprocessor macro function. This code block type isused throughout the NBC API. Macro functions are the only type of code block, which



use a parameter passing syntax similar to what you might see in a language like C orPascal.

Data segment blocks are used to define types and to declare variables. An NBC pro-gram can have zero or more data segments, which can be placed either outside of acode block or within a code block. Regardless of the location of the data segment, allvariables in an NBC program are global.

Threads

Subroutines

Macro Functions

Data Segments

3.2.1 Threads

Threads

The NXT implicitly supports multi-threading, thus an NBC thread directly correspondsto an NXT thread. Threads are defined using the thread keyword with the followingsyntax:

thread name// the threads code is placed here

endt

The name of the thread may be any legal identifier. A program must always have atleast one thread. If there is a thread named "main" then that thread will be the threadthat is started whenever the program is run. If none of the threads are named "main"then the very first thread that the compiler encounters in the source code will be themain thread. The maximum number of threads supported by the NXT is 256.

The body of a thread consists of a list of statements and optional data segments.Threads may be started by scheduling dependant threads using the precedes or followsstatements. You may also start a thread using the start statement. With the standardNXT firmware threads cannot be stopped by another thread. The only way to stop athread is by stopping all threads using the stop statement or by a thread stopping on itsown via the exit and exitto statements. Using the NBC/NBC enhanced firmware youcan also stop another thread using the stopthread statement.

thread mainprecedes waiter, worker// thread body goes here// finalize this thread and schedule the threads in the// specified range to executeexit // all dependants are automatically scheduled

endt

thread waiter// thread body goes here



// exit// exit is optional due to smart compiler finalization

endt

thread workerprecedes waiter// thread body goes hereexit // only one dependent - schedule it to execute

endt

endt

3.2.1.1 endt

End thread

A thread definition ends with the endt keyword.

thread main// thread body goes here

endt

3.2.2 Subroutines

Subroutines

Subroutines allow a single copy of some code to be shared between several differentcallers. This makes subroutines much more space efficient than macro functions. Sub-routines are defined using the subroutine keyword with the following syntax:

subroutine name// body of subroutinereturn // subroutines must end with a return statement

ends

A subroutine is just a special type of thread that is designed to be called explicitly byother threads or subroutines. Its name can be any legal identifier. Subroutines are notscheduled to run via the same mechanism that is used with threads. Instead, subroutinesand threads execute other subroutines by using the call statement (described in theStatements section).

thread main// body of main thread goes herecall mySub // compiler handles subroutine return addressexit // finalize execution (details handled by the compiler)

endt

subroutine mySub// body of subroutine goes herereturn // compiler handles the subroutine return address

ends



You can pass arguments into and out of subroutines using global variables. If a subrou-tine is designed to be used by concurrently executing threads then calls to the subrou-tine must be protected by acquiring a mutex prior to the subroutine call and releasingthe mutex after the call.

You can also call a thread as a subroutine using a slightly different syntax. This tech-nique is required if you want to call a subroutine which executes two threads simulta-neously. The subcall and subret statements must be used instead of call and return. Youalso must provide a global variable to store the return address as shown in the samplecode below.

thread main// thread body goes hereacquire ssMutexcall SharedSub // automatic return addressrelease ssMutex// calling a thread as a subroutinesubcall AnotherSub, anothersub_returnaddressexit

endt

subroutine SharedSub// subroutine body goes herereturn // return is required as the last operation

ends

thread AnotherSub// threads can be subroutines toosubret anothersub_returnaddress // manual return address

endt

After the subroutine completes executing, it returns back to the calling routine andprogram execution continues with the next statement following the subroutine call.The maximum number of threads and subroutines supported by the NXT firmware is256.

ends

3.2.2.1 ends

End subroutine or data segment.

A subroutine definition ends with the ends keyword.

subroutine doStuff// subroutine body goes here

ends

A data segment also ends with the ends keyword.

dseg segment// data definitions go here

dseg ends



3.2.3 Macro Functions

Macro Functions

It is often helpful to group a set of statements together into a single function, whichcan then be called as needed. NBC supports macro functions with arguments. Valuesmay be returned from a macro function by changing the value of one or more of thearguments within the body of the macro function.

Macro functions are defined using the following syntax:

#define name(argument_list) \// body of the macro function \// last line in macro function body has no \ at the end

Please note that the newline escape character (\) must be the very last character on theline. If it is followed by any whitespace or comments then the macro body is terminatedat that point and the next line is not considered to be part of the macro definition.

The argument list may be empty, or it may contain one or more argument definitions.An argument to a macro function has no type. Each argument is simply defined by itsname. Multiple arguments are separated by commas. Arguments to a macro functioncan either be inputs (constants or variables) for the code in the body of the functionto process or they can be outputs (variables only) for the code to modify and return.The following sample shows how to define a macro function to simplify the process ofdrawing text on the NXT LCD screen:

#define MyMacro(x, y, berase, msg) \mov dtArgs.Location.X, x \mov dtArgs.Location.Y, y \mov dtArgs.Options, berase \mov dtArgs.Text, msg \syscall DrawText, dtArgs

MyMacro(0, 0, TRUE, testing)MyMacro(10, 20, FALSE, Please Work)

NBC macro functions are always expanded inline by the NBC preprocessor. Thismeans that each call to a macro function results in another copy of the functions codebeing included in the program. Unless used judiciously, inline macro functions canlead to excessive code size.

3.2.4 Data Segments

Data Segments

Data segments contain all type definitions and variable declarations. Data segments aredefined using the following syntax:

dseg segment// type definitions and variable declarations go here

dseg ends



thread maindseg segment// or here - still global, though

dseg endsendt

segment

You can have multiple data segments in an NBC program. All variables are globalregardless of where they are declared. Once declared, they may be used within allthreads, subroutines, and macro functions. Their scope begins at the declaration andends at the end of the program.

Type Definitions

Structure Definitions

Variable Declarations

3.2.4.1 segment

Start a data segment.

A data segment starts with the segment keyword.

dseg segment// data definitions go here

dseg ends

3.2.4.2 Type Definitions

Type Definitions

Type definitions must be contained within a data segment. They are used to define newtype aliases or new aggregate types (i.e., structures). A type alias is defined using thetypedef keyword with the following syntax:

type_alias typedef existing_type

The new alias name may be any valid identifier. The existing type must be some typealready known by the compiler. It can be a native type or a user-defined type. Once atype alias has been defined it can be used in subsequent variable declarations and ag-gregate type definitions. The following is an example of a simple type alias definition:

big typedef dword // big is now an alias for the dword type



3.2.4.3 Structure Definitions

Structure Definitions

Structure definitions must also be contained within a data segment. They are usedto define a type which aggregates or contains other native or user-defined types. Astructure definition is defined using the struct and ends keywords with the followingsyntax:

TypeName structx bytey byte

TypeName ends

Structure definitions allow you to manage related data in a single combined type. Theycan be as simple or complex as the needs of your program dictate. The following is anexample of a fairly complex structure:

MyPoint structx bytey byte

MyPoint endsComplexStrut struct

value1 big // using a type aliasvalue2 sdwordbuffer byte[] // array of byteblen wordextrastuff MyPoint[] // array of structspt_1 MyPoint // struct contains struct instancespt_2 MyPoint

ComplexStruct ends

3.2.4.4 Variable Declarations

Variable Declarations

All variable declarations must be contained within a data segment. They are used todeclare variables for use in a code block such as a thread, subroutine, or macro function.A variable is declared using the following syntax:

var_name type_name optional_initialization

The variable name may be any valid identifier. The type name must be a type or typealias already known by the compiler. The optional initialization format depends onthe variable type, but for non-aggregate (scalar) types the format is simply a constantinteger or constant expression (which may not contain whitespace). See the exampleslater in this section.

The NXT firmware supports several different types of variables which are grouped intotwo categories: scalar types and aggregate types. Scalar types are a single integer valuewhich may be signed or unsigned and occupy one, two, or four bytes of memory. Thekeywords for declaring variables of a scalar type are listed in the following table:



Type Name Informationbyte, ubyte, db 8 bit unsignedsbyte 8 bit signedword, uword, dw 16 bit unsignedsword 16 bit signeddword, udword, dd 32 bit unsignedsdword 32 bit signedlong, ulong 32 bit unsigned (alias for dword,

udword)slong 32 bit signed (alias for sdword)float 32 bit IEEE 754 floating point typemutex Special type used for exclusive

subroutine access

Table 1. Scalar Types

Examples of scalar variable declarations are as follow:

dseg segmentx byte // initialized to zero by defaulty byte 12 // initialize to 12z sword -2048 // a signed valuemyVar big 0x12345 // use a type aliasvar1 dword 0xFF // value is 255myMutex mutex // mutexes ignore initialization, if presentbTrue byte 1 // byte variables can be used as booleans

dseg ends

Aggregate variables are either structures or arrays of some other type (either scalaror aggregate). Once a user-defined struct type has been defined it may be used todeclare a variable of that type. Similarly, user-defined struct types can be used inarray declarations. Arrays and structs may be nested (i.e., contained in other arraysor structures) as deeply as the needs of your program dictate, but nesting deeper than2 or 3 levels may lead to slower program execution due to NXT firmware memoryconstraints.

Examples of aggregate variable declarations are as follow:

dseg segmentbuffer byte[] // starts off emptymsg byte[] Testing// msg is an array of byte =// (0x54, 0x65, 0x73, 0x74, 0x69, 0x6e, 0x67, 0x00)data long[] {0xabcde, 0xfade0} // two values in the arraymyStruct ComplexStruct // declare an instance of a structPoints MyPoint[] // declare an array of a structsmsgs byte[][] // an array of an array of byte

dseg ends

Byte arrays may be initialized either by using braces containing a list of numeric val-ues ({val1, val2, ..., valN}) or by using a string constant delimited with single-quote



characters (Testing). Embedded single quote characters must be escaped using the\ character. The \ character can be part of the string by using two forward slashes:\. Arrays of any scalar type other than byte should be initialized using braces. Arraysof struct and nested arrays cannot be initialized.

3.2.4.4.1 byte The byte typeIn NBC the byte type is an unsigned 8-bit value. This type can store values from zeroto UCHAR_MAX. You can also define an unsigned 8-bit variable using the ubyte ordb keywords.

dseg segmentx byte 12b ubyte 0xE2test db 0xa0

dseg ends

3.2.4.4.2 ubyte The ubyte typeIn NBC the ubyte type is an unsigned 8-bit value. This type can store values from zeroto UCHAR_MAX. You can also define an unsigned 8-bit variable using the byte or dbkeywords.


dseg ends

3.2.4.4.3 db The db typeIn NBC the db type is an unsigned 8-bit value. This type can store values from zero toUCHAR_MAX. You can also define an unsigned 8-bit variable using the ubyte or bytekeywords.


dseg ends

3.2.4.4.4 sbyte The sbyte typeIn NBC the sbyte type is a signed 8-bit value. This type can store values fromSCHAR_MIN to SCHAR_MAX. The sbyte type is often used to store the ASCII valueof a single character.

dseg segmentch sbyte 12

dseg ends



3.2.4.4.5 word The word typeIn NBC the word type is an unsigned 16-bit value. This type can store values fromzero to UINT_MAX. You can also define an unsigned 16-bit variable using the uwordor dw keywords.

dseg segmentx word 0xfff0y uword 62450z dw 48500

dseg ends

3.2.4.4.6 uword The uword typeIn NBC the uword type is an unsigned 16-bit value. This type can store values fromzero to UINT_MAX. You can also define an unsigned 16-bit variable using the wordor dw keywords.


dseg ends

3.2.4.4.7 dw The dw typeIn NBC the dw type is an unsigned 16-bit value. This type can store values from zeroto UINT_MAX. You can also define an unsigned 16-bit variable using the uword orword keywords.


dseg ends

3.2.4.4.8 sword The sword typeIn NBC the sword type is a signed 16-bit value. This type can store values from INT_-MIN to INT_MAX.

dseg segmentx sword 0xfffy sword -23

dseg ends

3.2.4.4.9 dword The dword typeIn NBC the dword type is an unsigned 32-bit value. The range of values that can bestored in a ulong variable is from zero to ULONG_MAX.

dseg segment



a ulong 0xdeadbeefb long 80000c dword 150000d udword 200000e dd 400000

dseg ends

3.2.4.4.10 udword The udword typeIn NBC the udword type is an unsigned 32-bit value. The range of values that can bestored in a ulong variable is from zero to ULONG_MAX.

dseg segmenta ulong 0xdeadbeefb long 80000c dword 150000d udword 200000e dd 400000

dseg ends

3.2.4.4.11 dd The dd typeIn NBC the dd type is an unsigned 32-bit value. The range of values that can be storedin a ulong variable is from zero to ULONG_MAX.

dseg segmenta ulong 0xdeadbeefb long 80000c dword 150000d udword 200000e dd 400000

dseg ends

3.2.4.4.12 sdword The sdword typeIn NBC the sdword type is a signed 32-bit value. This type can store values fromLONG_MIN to LONG_MAX. You can also define a signed 32-bit variable using theslong keywords.

dseg segmentx slong 2147

nbc_guide

Documents