NXShield  v1.07
NXShield Library Reference by OpenElectrons.com
 All Classes Files Functions Variables Enumerations Enumerator Macros Pages
NXShield.h
Go to the documentation of this file.
1 
38 /*
39  * NXShield interface library
40  * Copyright (C) 2011 mindsensors.com
41  *
42  * This file is part of NXShield interface library.
43  * This library is free software; you can redistribute it and/or
44  * modify it under the terms of the GNU Lesser General Public
45  * License as published by the Free Software Foundation; either
46  * version 2.1 of the License, or (at your option) any later version.
47 
48  * This library is distributed in the hope that it will be useful,
49  * but WITHOUT ANY WARRANTY; without even the implied warranty of
50  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
51  * Lesser General Public License for more details.
52 
53  * You should have received a copy of the GNU Lesser General Public
54  * License along with this library; if not, write to the Free Software
55  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
56  */
57 
58 #ifndef NXShield_H
59 #define NXShield_H
60 
61 #include "SHDefines.h"
62 
63 // Motor control related constants.
64 #define SH_CONTROL_SPEED 0x01
65 #define SH_CONTROL_RAMP 0x02
66 #define SH_CONTROL_RELATIVE 0x04
67 #define SH_CONTROL_TACHO 0x08
68 #define SH_CONTROL_BRK 0x10
69 #define SH_CONTROL_ON 0x20
70 #define SH_CONTROL_TIME 0x40
71 #define SH_CONTROL_GO 0x80
72 
73 #define SH_STATUS_SPEED 0x01
74 #define SH_STATUS_RAMP 0x02
75 #define SH_STATUS_MOVING 0x04
76 #define SH_STATUS_TACHO 0x08
77 #define SH_STATUS_BREAK 0x10
78 #define SH_STATUS_OVERLOAD 0x20
79 #define SH_STATUS_TIME 0x40
80 #define SH_STATUS_STALL 0x80
81 
82 #define SH_COMMAND 0x41
83 #define SH_VOLTAGE 0x41
84 
85 #define SH_SETPT_M1 0x42
86 #define SH_SPEED_M1 0x46
87 #define SH_TIME_M1 0x47
88 #define SH_CMD_B_M1 0x48
89 #define SH_CMD_A_M1 0x49
90 
91 #define SH_SETPT_M2 0x4A
92 #define SH_SPEED_M2 0x4E
93 #define SH_TIME_M2 0x4F
94 #define SH_CMD_B_M2 0x50
95 #define SH_CMD_A_M2 0x51
96 
97 /*
98  * Read registers.
99  */
100 #define SH_POSITION_M1 0x62
101 #define SH_POSITION_M2 0x66
102 #define SH_STATUS_M1 0x72
103 #define SH_STATUS_M2 0x73
104 #define SH_TASKS_M1 0x76
105 #define SH_TASKS_M2 0x77
106 
107 #define SH_ENCODER_PID 0x7A
108 #define SH_SPEED_PID 0x80
109 #define SH_PASS_COUNT 0x86
110 #define SH_TOLERANCE 0x87
111 
112 /* constants to be used by user programs */
116 typedef enum {
117  SH_Motor_1 = 0x01,
118  SH_Motor_2 = 0x02,
120 } SH_Motor;
121 
122 /*
123  * \enum SH_Next_Action Next action related constants
124  */
125 typedef enum {
130 
134 typedef enum {
137 } SH_Direction;
138 
139 /*
140  * \enum SH_Move Tachometer movement related constants
141  */
142 typedef enum {
145 } SH_Move;
146 
147 /*
148  * \enum SH_Completion_Wait Whether to wait for motor to finish it's current task or not
149  */
150 typedef enum {
154 
155 /*
156  * Speed constants, these are just convenience constants,
157  * You can use any value between 0 and 100.
158  */
159 #define SH_Speed_Full 90
160 #define SH_Speed_Medium 60
161 #define SH_Speed_Slow 25
162 
163 /*
164  * NXShield has two banks, and each of them has different I2C address.
165  * each bank has 2 motors and 2 sensors.
166  *
167  */
172 #define SH_Bank_A 0x06
173 
177 #define SH_Bank_B 0x08
178 
179 
180 /*
181  * Sensor type primitives
182  *
183  */
184 
189 #define SH_Type_ANALOG_PASSIVE 0x01
190 
195 #define SH_Type_ANALOG_9VOLTS 0x02
196 
200 #define SH_Type_ANALOG_ACTIVE 0x02
201 
206 #define SH_Type_I2C 0x04
207 
212 #define SH_Type_ANALOG 0x08
213 
218 #define SH_Type_MIXED 0x10
219 
226 #define SH_Type_DATABIT0_HIGH 0x40
227 
232 #define SH_Type_DATABIT1_HIGH 0x80
233 
234 /*
235  * Sensor defines.
236  */
243 #define SH_S1 1
244 
250 #define SH_S2 2
251 
252 #include "NXShieldI2C.h"
253 #if defined(__AVR__)
254  #include <avr/io.h>
255  #include <avr/interrupt.h>
256 #endif
257 
261 class NXShieldBank : public NXShieldI2C
262 {
263 public:
265  NXShieldBank(uint8_t i2c_address = SH_Bank_A);
266 
275 
280  uint8_t nxshieldIssueCommand(char command);
281 
282  //
283  // Motor Operation APIs.
284  //
289  bool motorSetEncoderTarget(SH_Motor which_motor, long target);
290 
296  long motorGetEncoderTarget(SH_Motor which_motor);
297 
303  bool motorSetSpeed(SH_Motor which_motor, int speed);
304 
310  int8_t motorGetSpeed(SH_Motor which_motor);
311 
317  bool motorSetTimeToRun(SH_Motor which_motor, int seconds);
318 
324  uint8_t motorGetTimeToRun(SH_Motor which_motor);
325 
336  bool motorSetCommandRegB(SH_Motor which_motor, uint8_t value);
345  uint8_t motorGetCommandRegB(SH_Motor which_motor);
355  bool motorSetCommandRegA(SH_Motor which_motor, uint8_t value);
364  uint8_t motorGetCommandRegA(SH_Motor which_motor);
365 
371  int32_t motorGetEncoderPosition(SH_Motor which_motor);
372 
380  uint8_t motorGetStatusByte(SH_Motor which_motor);
381 
388  uint8_t motorGetTasksRunningByte(SH_Motor which_motor);
389 
397  bool motorSetEncoderPID(uint16_t Kp, uint16_t Ki, uint16_t Kd);
398 
406  bool motorSetSpeedPID(uint16_t Kp, uint16_t Ki, uint16_t Kd);
407 
415  bool motorSetPassCount(uint8_t pass_count);
416 
423  bool motorSetTolerance(uint8_t tolerance);
424 
429  bool motorReset();
430 
435  bool motorStartBothInSync();
436 
441  bool motorResetEncoder(SH_Motor which_motor);
442 
453  bool motorSetSpeedTimeAndControl(SH_Motor which_motors, int speed,
454  uint8_t duration, uint8_t control);
455 
469  long encoder, int speed,
470  uint8_t duration, uint8_t control);
471 
478  uint8_t motorIsTimeDone(SH_Motor which_motors);
479 
486  uint8_t motorWaitUntilTimeDone(SH_Motor which_motors);
487 
494  uint8_t motorIsTachoDone(SH_Motor which_motors);
495 
502  uint8_t motorWaitUntilTachoDone(SH_Motor which_motors);
503 
511  void motorRunUnlimited(SH_Motor which_motors, SH_Direction direction,
512  int speed);
513 
524  uint8_t motorRunSeconds(SH_Motor which_motors, SH_Direction direction,
525  int speed, uint8_t duration,
526  SH_Completion_Wait wait_for_completion,
527  SH_Next_Action next_action);
528 
541  uint8_t motorRunTachometer(SH_Motor which_motors, SH_Direction direction,
542  int speed, long tachometer,
543  SH_Move relative,
544  SH_Completion_Wait wait_for_completion,
545  SH_Next_Action next_action);
546 
558  uint8_t motorRunDegrees(SH_Motor which_motors, SH_Direction direction,
559  int speed, long degrees,
560  SH_Completion_Wait wait_for_completion,
561  SH_Next_Action next_action);
562 
574  uint8_t motorRunRotations(SH_Motor which_motors, SH_Direction direction,
575  int speed, long rotations,
576  SH_Completion_Wait wait_for_completion,
577  SH_Next_Action next_action);
578 
584  bool motorStop(SH_Motor which_motors, SH_Next_Action next_action);
585 
586 
587  //
588  // NXShield sensor functions.
589  //
590 public:
597  bool sensorSetType(uint8_t which_sensor, uint8_t sensor_type);
598 
604  int sensorReadRaw(uint8_t which_sensor);
605 
606 };
607 
613 {
614 private:
615 
616 public:
618  NXShieldBankB(uint8_t i2c_address_b = SH_Bank_B);
624  int sensorReadRaw(uint8_t which_sensor);
625 
632  bool sensorSetType(uint8_t which_sensor, uint8_t sensor_type);
633 };
634 
635 
639 class NXShield
640 {
641 public:
645  uint8_t m_protocol;
652 
654  NXShield(uint8_t i2c_address_a = SH_Bank_A,
655  uint8_t i2c_address_b = SH_Bank_B);
656 
662  void init(SH_Protocols protocol=SH_HardwareI2C);
663 
667  void initLEDTimers();
668 
674 
675 
681  bool getButtonState(uint8_t btn);
682 
690  void waitForButtonPress(uint8_t btn, uint8_t led_pattern=1);
691 
699  void ledSetRGB(uint8_t red = 0, uint8_t green = 0, uint8_t blue = 0);
700 
705  void ledBreathingPattern();
706 
711  void ledHeartBeatPattern();
712 };
713 
718 extern bool format_bin(uint8_t i, char *s);
719 
720 #endif
This class implements I2C interfaces used by NXShield.
Definition: NXShieldI2C.h:32
uint8_t motorRunSeconds(SH_Motor which_motors, SH_Direction direction, int speed, uint8_t duration, SH_Completion_Wait wait_for_completion, SH_Next_Action next_action)
Definition: NXShield.cpp:483
This class defines methods to access NXShield features.
Definition: NXShield.h:639
uint8_t motorIsTimeDone(SH_Motor which_motors)
Definition: NXShield.cpp:364
bool motorSetEncoderTarget(SH_Motor which_motor, long target)
Definition: NXShield.cpp:158
int nxshieldGetBatteryVoltage()
Definition: NXShield.cpp:143
uint8_t motorRunDegrees(SH_Motor which_motors, SH_Direction direction, int speed, long degrees, SH_Completion_Wait wait_for_completion, SH_Next_Action next_action)
Definition: NXShield.cpp:544
Definition: SHDefines.h:61
SH_Next_Action
Definition: NXShield.h:125
bool motorSetTolerance(uint8_t tolerance)
Definition: NXShield.cpp:268
Definition: NXShield.h:119
int sensorReadRaw(uint8_t which_sensor)
Definition: NXShield.cpp:693
Definition: NXShield.h:128
SH_Completion_Wait
Definition: NXShield.h:150
void initLEDTimers()
Definition: NXShield.cpp:119
bool motorSetCommandRegA(SH_Motor which_motor, uint8_t value)
Definition: NXShield.cpp:209
uint8_t m_protocol
Definition: NXShield.h:645
Definition: NXShield.h:151
uint8_t motorGetTasksRunningByte(SH_Motor which_motor)
Definition: NXShield.cpp:235
uint8_t motorGetCommandRegB(SH_Motor which_motor)
Definition: NXShield.cpp:202
SH_Protocols
Protocols supported by NXShield.
Definition: SHDefines.h:60
uint8_t nxshieldIssueCommand(char command)
Definition: NXShield.cpp:151
bool motorSetCommandRegB(SH_Motor which_motor, uint8_t value)
Definition: NXShield.cpp:197
Definition: NXShield.h:127
Definition: NXShield.h:117
int8_t motorGetSpeed(SH_Motor which_motor)
Definition: NXShield.cpp:177
Definition: NXShield.h:152
Definition: NXShield.h:143
uint8_t motorWaitUntilTimeDone(SH_Motor which_motors)
Definition: NXShield.cpp:396
bool motorStop(SH_Motor which_motors, SH_Next_Action next_action)
Definition: NXShield.cpp:572
bool motorSetEncoderPID(uint16_t Kp, uint16_t Ki, uint16_t Kd)
Definition: NXShield.cpp:243
long motorGetEncoderTarget(SH_Motor which_motor)
Definition: NXShield.cpp:164
SH_Direction
Definition: NXShield.h:134
NXShield has two banks. Bank B has few differences from Bank A. This class defines overriding methods...
Definition: NXShield.h:612
void waitForButtonPress(uint8_t btn, uint8_t led_pattern=1)
Definition: NXShield.cpp:817
void ledBreathingPattern()
Definition: NXShield.cpp:833
uint8_t motorGetTimeToRun(SH_Motor which_motor)
Definition: NXShield.cpp:189
This class defines methods for the NXShield Bank(s).
Definition: NXShield.h:261
bool motorSetSpeed(SH_Motor which_motor, int speed)
Definition: NXShield.cpp:172
bool motorSetSpeedPID(uint16_t Kp, uint16_t Ki, uint16_t Kd)
Definition: NXShield.cpp:252
uint8_t motorRunTachometer(SH_Motor which_motors, SH_Direction direction, int speed, long tachometer, SH_Move relative, SH_Completion_Wait wait_for_completion, SH_Next_Action next_action)
Definition: NXShield.cpp:503
Definition: NXShield.h:118
NXShieldBankB(uint8_t i2c_address_b=SH_Bank_B)
Definition: NXShield.cpp:130
NXShield(uint8_t i2c_address_a=SH_Bank_A, uint8_t i2c_address_b=SH_Bank_B)
Definition: NXShield.cpp:54
bool motorSetPassCount(uint8_t pass_count)
Definition: NXShield.cpp:261
NXShieldBank(uint8_t i2c_address=SH_Bank_A)
Definition: NXShield.cpp:136
int32_t motorGetEncoderPosition(SH_Motor which_motor)
Definition: NXShield.cpp:221
Definition: NXShield.h:144
bool motorSetSpeedTimeAndControl(SH_Motor which_motors, int speed, uint8_t duration, uint8_t control)
Definition: NXShield.cpp:298
SH_Move
Definition: NXShield.h:142
uint8_t motorRunRotations(SH_Motor which_motors, SH_Direction direction, int speed, long rotations, SH_Completion_Wait wait_for_completion, SH_Next_Action next_action)
Definition: NXShield.cpp:557
void ledHeartBeatPattern()
Definition: NXShield.cpp:858
uint8_t motorGetCommandRegA(SH_Motor which_motor)
Definition: NXShield.cpp:214
void initProtocols(SH_Protocols protocol=SH_HardwareI2C)
Definition: NXShield.cpp:78
bool motorStartBothInSync()
Definition: NXShield.cpp:283
uint8_t motorWaitUntilTachoDone(SH_Motor which_motors)
Definition: NXShield.cpp:440
SH_Motor
Definition: NXShield.h:116
#define SH_Bank_B
Definition: NXShield.h:177
bool sensorSetType(uint8_t which_sensor, uint8_t sensor_type)
Definition: NXShield.cpp:644
bool motorResetEncoder(SH_Motor which_motor)
Definition: NXShield.cpp:289
bool getButtonState(uint8_t btn)
Definition: NXShield.cpp:811
void init(SH_Protocols protocol=SH_HardwareI2C)
Definition: NXShield.cpp:60
uint8_t motorIsTachoDone(SH_Motor which_motors)
Definition: NXShield.cpp:409
Definition: NXShield.h:126
#define SH_Bank_A
Definition: NXShield.h:172
void motorRunUnlimited(SH_Motor which_motors, SH_Direction direction, int speed)
Definition: NXShield.cpp:472
Definition: NXShield.h:136
bool motorReset()
Definition: NXShield.cpp:277
NXShieldBank bank_a
Definition: NXShield.h:648
bool motorSetEncoderSpeedTimeAndControl(SH_Motor which_motors, long encoder, int speed, uint8_t duration, uint8_t control)
Definition: NXShield.cpp:339
Definition: NXShield.h:135
int sensorReadRaw(uint8_t which_sensor)
Definition: NXShield.cpp:628
bool format_bin(uint8_t i, char *s)
Definition: NXShield.cpp:37
bool motorSetTimeToRun(SH_Motor which_motor, int seconds)
Definition: NXShield.cpp:184
NXShieldBankB bank_b
Definition: NXShield.h:651
void ledSetRGB(uint8_t red=0, uint8_t green=0, uint8_t blue=0)
Definition: NXShield.cpp:793
uint8_t motorGetStatusByte(SH_Motor which_motor)
Definition: NXShield.cpp:228
bool sensorSetType(uint8_t which_sensor, uint8_t sensor_type)
Definition: NXShield.cpp:586