This repository has been archived by the owner on Sep 6, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
API.h
1618 lines (1570 loc) · 64.9 KB
/
API.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/** @file API.h
* @brief Provides the high-level user functionality intended for use by typical VEX Cortex
* programmers.
*
* This file should be included for you in the predefined stubs in each new VEX Cortex PROS
* project through the inclusion of "main.h". In any new C source file, it is advisable to
* include main.h instead of referencing API.h by name, to better handle any nomenclature
* changes to this file or its contents.
*
* Copyright (c) 2011-2016, Purdue University ACM SIGBots.
* All rights reserved.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
* PROS contains FreeRTOS (http://www.freertos.org) whose source code may be
* obtained from http://sourceforge.net/projects/freertos/files/ or on request.
*/
#ifndef API_H_
#define API_H_
// System includes
#include <stdlib.h>
#include <stdbool.h>
#include <stdarg.h>
#include <stdint.h>
// Begin C++ extern to C
#ifdef __cplusplus
extern "C" {
#endif
// -------------------- VEX competition functions --------------------
/**
* DOWN button (valid on channels 5, 6, 7, 8)
*/
#define JOY_DOWN 1
/**
* LEFT button (valid on channels 7, 8)
*/
#define JOY_LEFT 2
/**
* UP button (valid on channels 5, 6, 7, 8)
*/
#define JOY_UP 4
/**
* RIGHT button (valid on channels 7, 8)
*/
#define JOY_RIGHT 8
/**
* Analog axis for the X acceleration from the VEX Joystick.
*/
#define ACCEL_X 5
/**
* Analog axis for the Y acceleration from the VEX Joystick.
*/
#define ACCEL_Y 6
/**
* Returns true if the robot is in autonomous mode, or false otherwise.
*
* While in autonomous mode, joystick inputs will return a neutral value, but serial port
* communications (even over VexNET) will still work properly.
*/
bool isAutonomous();
/**
* Returns true if the robot is enabled, or false otherwise.
*
* While disabled via the VEX Competition Switch or VEX Field Controller, motors will not
* function. However, the digital I/O ports can still be changed, which may indirectly affect
* the robot state (e.g. solenoids). Avoid performing externally visible actions while
* disabled (the kernel should take care of this most of the time).
*/
bool isEnabled();
/**
* Returns true if a joystick is connected to the specified slot number (1 or 2), or false
* otherwise.
*
* Useful for automatically merging joysticks for one operator, or splitting for two. This
* function does not work properly during initialize() or initializeIO() and can return false
* positives. It should be checked once and stored at the beginning of operatorControl().
*
* @param joystick the joystick slot to check
*/
bool isJoystickConnected(unsigned char joystick);
/**
* Returns true if a VEX field controller or competition switch is connected, or false
* otherwise.
*
* When in online mode, the switching between autonomous() and operatorControl() tasks is
* managed by the PROS kernel.
*/
bool isOnline();
/**
* Gets the value of a control axis on the VEX joystick. Returns the value from -127 to 127,
* or 0 if no joystick is connected to the requested slot.
*
* @param joystick the joystick slot to check
* @param axis one of 1, 2, 3, 4, ACCEL_X, or ACCEL_Y
*/
int joystickGetAnalog(unsigned char joystick, unsigned char axis);
/**
* Gets the value of a button on the VEX joystick. Returns true if that button is pressed, or
* false otherwise. If no joystick is connected to the requested slot, returns false.
*
* @param joystick the joystick slot to check
* @param buttonGroup one of 5, 6, 7, or 8 to request that button as labelled on the joystick
* @param button one of JOY_UP, JOY_DOWN, JOY_LEFT, or JOY_RIGHT; requesting JOY_LEFT or
* JOY_RIGHT for groups 5 or 6 will cause an undefined value to be returned
*/
bool joystickGetDigital(unsigned char joystick, unsigned char buttonGroup,
unsigned char button);
/**
* Returns the backup battery voltage in millivolts.
*
* If no backup battery is connected, returns 0.
*/
unsigned int powerLevelBackup();
/**
* Returns the main battery voltage in millivolts.
*
* In rare circumstances, this method might return 0. Check the output value for reasonability
* before blindly blasting the user.
*/
unsigned int powerLevelMain();
/**
* Sets the team name displayed to the VEX field control and VEX Firmware Upgrade.
*
* @param name a string containing the team name; only the first eight characters will be shown
*/
void setTeamName(const char *name);
// -------------------- Pin control functions --------------------
/**
* There are 8 available analog I/O on the Cortex.
*/
#define BOARD_NR_ADC_PINS 8
/**
* There are 27 available I/O on the Cortex that can be used for digital communication.
*
* This excludes the crystal ports but includes the Communications, Speaker, and Analog ports.
*
* The motor ports are not on the Cortex and are thus excluded from this count. Pin 0 is the
* Speaker port, pins 1-12 are the standard Digital I/O, 13-20 are the Analog I/O, 21+22 are
* UART1, 23+24 are UART2, and 25+26 are the I2C port.
*/
#define BOARD_NR_GPIO_PINS 27
/**
* Used for digitalWrite() to specify a logic HIGH state to output.
*
* In reality, using any non-zero expression or "true" will work to set a pin to HIGH.
*/
#define HIGH 1
/**
* Used for digitalWrite() to specify a logic LOW state to output.
*
* In reality, using a zero expression or "false" will work to set a pin to LOW.
*/
#define LOW 0
/**
* pinMode() state for digital input, with pullup.
*
* This is the default state for the 12 Digital pins. The pullup causes the input to read as
* "HIGH" when unplugged, but is fairly weak and can safely be driven by most sources. Many VEX
* digital sensors rely on this behavior and cannot be used with INPUT_FLOATING.
*/
#define INPUT 0x0A
/**
* pinMode() state for analog inputs.
*
* This is the default state for the 8 Analog pins and the Speaker port. This only works on
* pins with analog input capabilities; use anywhere else results in undefined behavior.
*/
#define INPUT_ANALOG 0x00
/**
* pinMode() state for digital input, without pullup.
*
* Beware of power consumption, as digital inputs left "floating" may switch back and forth
* and cause spurious interrupts.
*/
#define INPUT_FLOATING 0x04
/**
* pinMode() state for digital output, push-pull.
*
* This is the mode which should be used to output a digital HIGH or LOW value from the Cortex.
* This mode is useful for pneumatic solenoid valves and VEX LEDs.
*/
#define OUTPUT 0x01
/**
* pinMode() state for open-drain outputs.
*
* This is useful in a few cases for external electronics and should not be used for the VEX
* solenoid or LEDs.
*/
#define OUTPUT_OD 0x05
/**
* Calibrates the analog sensor on the specified channel.
*
* This method assumes that the true sensor value is not actively changing at this time and
* computes an average from approximately 500 samples, 1 ms apart, for a 0.5 s period of
* calibration. The average value thus calculated is returned and stored for later calls to the
* analogReadCalibrated() and analogReadCalibratedHR() functions. These functions will return
* the difference between this value and the current sensor value when called.
*
* Do not use this function in initializeIO(), or when the sensor value might be unstable
* (gyro rotation, accelerometer movement).
*
* This function may not work properly if the VEX Cortex is tethered to a PC using the orange
* USB A to A cable and has no VEX 7.2V Battery connected and powered on, as the VEX Battery
* provides power to sensors.
*
* @param channel the channel to calibrate from 1-8
* @return the average sensor value computed by this function
*/
int analogCalibrate(unsigned char channel);
/**
* Reads an analog input channel and returns the 12-bit value.
*
* The value returned is undefined if the analog pin has been switched to a different mode.
* This function is Wiring-compatible with the exception of the larger output range. The
* meaning of the returned value varies depending on the sensor attached.
*
* This function may not work properly if the VEX Cortex is tethered to a PC using the orange
* USB A to A cable and has no VEX 7.2V Battery connected and powered on, as the VEX Battery
* provides power to sensors.
*
* @param channel the channel to read from 1-8
* @return the analog sensor value, where a value of 0 reflects an input voltage of nearly 0 V
* and a value of 4095 reflects an input voltage of nearly 5 V
*/
int analogRead(unsigned char channel);
/**
* Reads the calibrated value of an analog input channel.
*
* The analogCalibrate() function must be run first on that channel. This function is
* inappropriate for sensor values intended for integration, as round-off error can accumulate
* causing drift over time. Use analogReadCalibratedHR() instead.
*
* This function may not work properly if the VEX Cortex is tethered to a PC using the orange
* USB A to A cable and has no VEX 7.2V Battery connected and powered on, as the VEX Battery
* provides power to sensors.
*
* @param channel the channel to read from 1-8
* @return the difference of the sensor value from its calibrated default from -4095 to 4095
*/
int analogReadCalibrated(unsigned char channel);
/**
* Reads the calibrated value of an analog input channel 1-8 with enhanced precision.
*
* The analogCalibrate() function must be run first. This is intended for integrated sensor
* values such as gyros and accelerometers to reduce drift due to round-off, and should not be
* used on a sensor such as a line tracker or potentiometer.
*
* The value returned actually has 16 bits of "precision", even though the ADC only reads
* 12 bits, so that errors induced by the average value being between two values come out
* in the wash when integrated over time. Think of the value as the true value times 16.
*
* This function may not work properly if the VEX Cortex is tethered to a PC using the orange
* USB A to A cable and has no VEX 7.2V Battery connected and powered on, as the VEX Battery
* provides power to sensors.
*
* @param channel the channel to read from 1-8
* @return the difference of the sensor value from its calibrated default from -16384 to 16384
*/
int analogReadCalibratedHR(unsigned char channel);
/**
* Gets the digital value (1 or 0) of a pin configured as a digital input.
*
* If the pin is configured as some other mode, the digital value which reflects the current
* state of the pin is returned, which may or may not differ from the currently set value. The
* return value is undefined for pins configured as Analog inputs, or for ports in use by a
* Communications interface. This function is Wiring-compatible.
*
* This function may not work properly if the VEX Cortex is tethered to a PC using the orange
* USB A to A cable and has no VEX 7.2V Battery connected and powered on, as the VEX Battery
* provides power to sensors.
*
* @param pin the pin to read from 1-26
* @return true if the pin is HIGH, or false if it is LOW
*/
bool digitalRead(unsigned char pin);
/**
* Sets the digital value (1 or 0) of a pin configured as a digital output.
*
* If the pin is configured as some other mode, behavior is undefined. This function is
* Wiring-compatible.
*
* @param pin the pin to write from 1-26
* @param value an expression evaluating to "true" or "false" to set the output to HIGH or LOW
* respectively, or the constants HIGH or LOW themselves
*/
void digitalWrite(unsigned char pin, bool value);
/**
* Configures the pin as an input or output with a variety of settings.
*
* Do note that INPUT by default turns on the pull-up resistor, as most VEX sensors are
* open-drain active low. It should not be a big deal for most push-pull sources. This function
* is Wiring-compatible.
*
* @param pin the pin to modify from 1-26
* @param mode one of INPUT, INPUT_ANALOG, INPUT_FLOATING, OUTPUT, or OUTPUT_OD
*/
void pinMode(unsigned char pin, unsigned char mode);
/*
* Digital port 10 cannot be used as an interrupt port, or for an encoder. Plan accordingly.
*/
/**
* When used in ioSetInterrupt(), triggers an interrupt on rising edges (LOW to HIGH).
*/
#define INTERRUPT_EDGE_RISING 1
/**
* When used in ioSetInterrupt(), triggers an interrupt on falling edges (HIGH to LOW).
*/
#define INTERRUPT_EDGE_FALLING 2
/**
* When used in ioSetInterrupt(), triggers an interrupt on both rising and falling edges
* (LOW to HIGH or HIGH to LOW).
*/
#define INTERRUPT_EDGE_BOTH 3
/**
* Type definition for interrupt handlers. Such functions must accept one argument indicating
* the pin which changed.
*/
typedef void (*InterruptHandler)(unsigned char pin);
/**
* Disables interrupts on the specified pin.
*
* Disabling interrupts on interrupt pins which are not in use conserves processing time.
*
* @param pin the pin on which to reset interrupts from 1-9,11-12
*/
void ioClearInterrupt(unsigned char pin);
/**
* Sets up an interrupt to occur on the specified pin, and resets any counters or timers
* associated with the pin.
*
* Each time the specified change occurs, the function pointer passed in will be called with
* the pin that changed as an argument. Enabling pin-change interrupts consumes processing
* time, so it is best to only enable necessary interrupts and to keep the InterruptHandler
* function short. Pin change interrupts can only be enabled on pins 1-9 and 11-12.
*
* Do not use API functions such as delay() inside the handler function, as the function will
* run in an ISR where the scheduler is paused and no other interrupts can execute. It is best
* to quickly update some state and allow a task to perform the work.
*
* Do not use this function on pins that are also being used by the built-in ultrasonic or
* shaft encoder drivers, or on pins which have been switched to output mode.
*
* @param pin the pin on which to enable interrupts from 1-9,11-12
* @param edges one of INTERRUPT_EDGE_RISING, INTERRUPT_EDGE_FALLING, or INTERRUPT_EDGE_BOTH
* @param handler the function to call when the condition is satisfied
*/
void ioSetInterrupt(unsigned char pin, unsigned char edges, InterruptHandler handler);
// -------------------- Physical output control functions --------------------
/**
* Gets the last set speed of the specified motor channel.
*
* This speed may have been set by any task or the PROS kernel itself. This is not guaranteed
* to be the speed that the motor is actually running at, or even the speed currently being
* sent to the motor, due to latency in the Motor Controller 29 protocol and physical loading.
* To measure actual motor shaft revolution speed, attach a VEX Integrated Motor Encoder or
* VEX Quadrature Encoder and use the velocity functions associated with each.
*
* @param channel the motor channel to fetch from 1-10
* @return the speed last sent to this channel; -127 is full reverse and 127 is full forward,
* with 0 being off
*/
int motorGet(unsigned char channel);
/**
* Sets the speed of the specified motor channel.
*
* Do not use motorSet() with the same channel argument from two different tasks. It is safe to
* use motorSet() with different channel arguments from different tasks.
*
* @param channel the motor channel to modify from 1-10
* @param speed the new signed speed; -127 is full reverse and 127 is full forward, with 0
* being off
*/
void motorSet(unsigned char channel, int speed);
/**
* Stops the motor on the specified channel, equivalent to calling motorSet() with an argument
* of zero.
*
* This performs a coasting stop, not an active brake. Since motorStop is similar to
* motorSet(0), see the note for motorSet() about use from multiple tasks.
*
* @param channel the motor channel to stop from 1-10
*/
void motorStop(unsigned char channel);
/**
* Stops all motors; significantly faster than looping through all motor ports and calling
* motorSet(channel, 0) on each one.
*/
void motorStopAll();
/**
* Initializes VEX speaker support.
*
* The VEX speaker is not thread safe; it can only be used from one task at a time. Using the
* VEX speaker may impact robot performance. Teams may benefit from an if statement that only
* enables sound if isOnline() returns false.
*/
void speakerInit();
/**
* Plays up to three RTTTL (Ring Tone Text Transfer Language) songs simultaneously over the
* VEX speaker. The audio is mixed to allow polyphonic sound to be played. Many simple songs
* are available in RTTTL format online, or compose your own.
*
* The song must not be NULL, but unused tracks within the song can be set to NULL. If any of
* the three song tracks is invalid, the result of this function is undefined.
*
* The VEX speaker is not thread safe; it can only be used from one task at a time. Using the
* VEX speaker may impact robot performance. Teams may benefit from an if statement that only
* enables sound if isOnline() returns false.
*
* @param songs an array of up to three (3) RTTTL songs as string values to play
*/
void speakerPlayArray(const char * * songs);
/**
* Plays an RTTTL (Ring Tone Text Transfer Language) song over the VEX speaker. Many simple
* songs are available in RTTTL format online, or compose your own.
*
* The song must not be NULL. If an invalid song is specified, the result of this function is
* undefined.
*
* The VEX speaker is not thread safe; it can only be used from one task at a time. Using the
* VEX speaker may impact robot performance. Teams may benefit from an if statement that only
* enables sound if isOnline() returns false.
*
* @param song the RTTTL song as a string value to play
*/
void speakerPlayRtttl(const char *song);
/**
* Powers down and disables the VEX speaker.
*
* If a song is currently being played in another task, the behavior of this function is
* undefined, since the VEX speaker is not thread safe.
*/
void speakerShutdown();
// -------------------- VEX sensor control functions --------------------
/**
* IME addresses end at 0x1F. Actually using more than 10 (address 0x1A) encoders will cause
* unreliable communications.
*/
#define IME_ADDR_MAX 0x1F
/**
* Initializes all IMEs.
*
* IMEs are assigned sequential incrementing addresses, beginning with the first IME on the
* chain (closest to the VEX Cortex I2C port). Therefore, a given configuration of IMEs will
* always have the same ID assigned to each encoder. The addresses range from 0 to
* IME_ADDR_MAX, so the first encoder gets 0, the second gets 1, ...
*
* This function should most likely be used in initialize(). Do not use it in initializeIO() or
* at any other time when the scheduler is paused (like an interrupt). Checking the return
* value of this function is important to ensure that all IMEs are plugged in and responding as
* expected.
*
* This function, unlike the other IME functions, is not thread safe. If using imeInitializeAll
* to re-initialize encoders, calls to other IME functions might behave unpredictably during
* this function's execution.
*
* @return the number of IMEs successfully initialized.
*/
unsigned int imeInitializeAll();
/**
* Gets the current 32-bit count of the specified IME.
*
* Much like the count for a quadrature encoder, the tick count is signed and cumulative.
* The value reflects total counts since the last reset. Different VEX Motor Encoders have a
* different number of counts per revolution:
*
* * \c 240.448 for the 269 IME
* * \c 627.2 for the 393 IME in high torque mode (factory default)
* * \c 392 for the 393 IME in high speed mode
*
* If the IME address is invalid, or the IME has not been reset or initialized, the value
* stored in *value is undefined.
*
* @param address the IME address to fetch from 0 to IME_ADDR_MAX
* @param value a pointer to the location where the value will be stored (obtained using the
* "&" operator on the target variable name e.g. <code>imeGet(2, &counts)</code>)
* @return true if the count was successfully read and the value stored in *value is valid;
* false otherwise
*/
bool imeGet(unsigned char address, int *value);
/**
* Gets the current rotational velocity of the specified IME.
*
* In this version of PROS, the velocity is positive if the IME count is increasing and
* negative if the IME count is decreasing. The velocity is in RPM of the internal encoder
* wheel. Since checking the IME for its type cannot reveal whether the motor gearing is
* high speed or high torque (in the 2-Wire Motor 393 case), the user must divide the return
* value by the number of output revolutions per encoder revolution:
*
* * \c 30.056 for the 269 IME
* * \c 39.2 for the 393 IME in high torque mode (factory default)
* * \c 24.5 for the 393 IME in high speed mode
*
* If the IME address is invalid, or the IME has not been reset or initialized, the value
* stored in *value is undefined.
*
* @param address the IME address to fetch from 0 to IME_ADDR_MAX
* @param value a pointer to the location where the value will be stored (obtained using the
* "&" operator on the target variable name e.g. <code>imeGetVelocity(2, &counts)</code>)
* @return true if the velocity was successfully read and the value stored in *value is valid;
* false otherwise
*/
bool imeGetVelocity(unsigned char address, int *value);
/**
* Resets the specified IME's counters to zero.
*
* This method can be used while the IME is rotating.
*
* @param address the IME address to reset from 0 to IME_ADDR_MAX
* @return true if the reset succeeded; false otherwise
*/
bool imeReset(unsigned char address);
/**
* Shuts down all IMEs on the chain; their addresses return to the default and the stored
* counts and velocities are lost. This function, unlike the other IME functions, is not
* thread safe.
*
* To use the IME chain again, wait at least 0.25 seconds before using imeInitializeAll again.
*/
void imeShutdown();
/**
* Reference type for an initialized gyro.
*
* Gyro information is stored as an opaque pointer to a structure in memory; as this is a
* pointer type, it can be safely passed or stored by value.
*/
typedef void * Gyro;
/**
* Gets the current gyro angle in degrees, rounded to the nearest degree.
*
* There are 360 degrees in a circle.
*
* @param gyro the Gyro object from gyroInit() to read
* @return the signed and cumulative number of degrees rotated around the gyro's vertical axis
* since the last start or reset
*/
int gyroGet(Gyro gyro);
/**
* Initializes and enables a gyro on an analog port.
*
* NULL will be returned if the port is invalid or the gyro is already in use. Initializing a
* gyro implicitly calibrates it and resets its count. Do not move the robot while the gyro is
* being calibrated. It is suggested to call this function in initialize() and to place the
* robot in its final position before powering it on.
*
* The multiplier parameter can tune the gyro to adapt to specific sensors. The default value
* at this time is 196; higher values will increase the number of degrees reported for a fixed
* actual rotation, while lower values will decrease the number of degrees reported. If your
* robot is consistently turning too far, increase the multiplier, and if it is not turning
* far enough, decrease the multiplier.
*
* @param port the analog port to use from 1-8
* @param multiplier an optional constant to tune the gyro readings; use 0 for the default
* value
* @return a Gyro object to be stored and used for later calls to gyro functions
*/
Gyro gyroInit(unsigned char port, unsigned short multiplier);
/**
* Resets the gyro to zero.
*
* It is safe to use this method while a gyro is enabled. It is not necessary to call this
* method before stopping or starting a gyro.
*
* @param gyro the Gyro object from gyroInit() to reset
*/
void gyroReset(Gyro gyro);
/**
* Stops and disables the gyro.
*
* Gyros use processing power, so disabling unused gyros increases code performance.
* The gyro's position will be retained.
*
* @param gyro the Gyro object from gyroInit() to stop
*/
void gyroShutdown(Gyro gyro);
/**
* Reference type for an initialized encoder.
*
* Encoder information is stored as an opaque pointer to a structure in memory; as this is a
* pointer type, it can be safely passed or stored by value.
*/
typedef void * Encoder;
/**
* Gets the number of ticks recorded by the encoder.
*
* There are 360 ticks in one revolution.
*
* @param enc the Encoder object from encoderInit() to read
* @return the signed and cumulative number of counts since the last start or reset
*/
int encoderGet(Encoder enc);
/**
* Initializes and enables a quadrature encoder on two digital ports.
*
* Neither the top port nor the bottom port can be digital port 10. NULL will be returned if
* either port is invalid or the encoder is already in use. Initializing an encoder implicitly
* resets its count.
*
* @param portTop the "top" wire from the encoder sensor with the removable cover side UP
* @param portBottom the "bottom" wire from the encoder sensor
* @param reverse if "true", the sensor will count in the opposite direction
* @return an Encoder object to be stored and used for later calls to encoder functions
*/
Encoder encoderInit(unsigned char portTop, unsigned char portBottom, bool reverse);
/**
* Resets the encoder to zero.
*
* It is safe to use this method while an encoder is enabled. It is not necessary to call this
* method before stopping or starting an encoder.
*
* @param enc the Encoder object from encoderInit() to reset
*/
void encoderReset(Encoder enc);
/**
* Stops and disables the encoder.
*
* Encoders use processing power, so disabling unused encoders increases code performance.
* The encoder's count will be retained.
*
* @param enc the Encoder object from encoderInit() to stop
*/
void encoderShutdown(Encoder enc);
/**
* This value is returned if the sensor cannot find a reasonable value to return.
*/
#define ULTRA_BAD_RESPONSE -1
/**
* Reference type for an initialized ultrasonic sensor.
*
* Ultrasonic information is stored as an opaque pointer to a structure in memory; as this is a
* pointer type, it can be safely passed or stored by value.
*/
typedef void * Ultrasonic;
/**
* Gets the current ultrasonic sensor value in centimeters.
*
* If no object was found or if the ultrasonic sensor is polled while it is pinging and waiting
* for a response, -1 (ULTRA_BAD_RESPONSE) is returned.
* If the ultrasonic sensor was never started, the return value is undefined. Round and fluffy
* objects can cause inaccurate values to be returned.
*
* @param ult the Ultrasonic object from ultrasonicInit() to read
* @return the distance to the nearest object in centimeters
*/
int ultrasonicGet(Ultrasonic ult);
/**
* Initializes an ultrasonic sensor on the specified digital ports.
*
* The ultrasonic sensor will be polled in the background in concert with the other sensors
* registered using this method. NULL will be returned if either port is invalid or the
* ultrasonic sensor port is already in use.
*
* @param portEcho the port connected to the orange cable from 1-9,11-12
* @param portPing the port connected to the yellow cable from 1-12
* @return an Ultrasonic object to be stored and used for later calls to ultrasonic functions
*/
Ultrasonic ultrasonicInit(unsigned char portEcho, unsigned char portPing);
/**
* Stops and disables the ultrasonic sensor.
*
* The last distance it had before stopping will be retained. One more ping operation may occur
* before the sensor is fully disabled.
*
* @param ult the Ultrasonic object from ultrasonicInit() to stop
*/
void ultrasonicShutdown(Ultrasonic ult);
// -------------------- Custom sensor control functions --------------------
// ---- I2C port control ----
/**
* i2cRead - Reads the specified number of data bytes from the specified 7-bit I2C address. The
* bytes will be stored at the specified location. Returns true if successful or false if
* failed. If only some bytes could be read, false is still returned.
*
* The I2C address should be right-aligned; the R/W bit is automatically supplied.
*
* Since most I2C devices use an 8-bit register architecture, this method has limited
* usefulness. Consider i2cReadRegister instead for the vast majority of applications.
*/
bool i2cRead(uint8_t addr, uint8_t *data, uint16_t count);
/**
* i2cReadRegister - Reads the specified amount of data from the given register address on
* the specified 7-bit I2C address. Returns true if successful or false if failed. If only some
* bytes could be read, false is still returned.
*
* The I2C address should be right-aligned; the R/W bit is automatically supplied.
*
* Most I2C devices support an auto-increment address feature, so using this method to read
* more than one byte will usually read a block of sequential registers. Try to merge reads to
* separate registers into a larger read using this function whenever possible to improve code
* reliability, even if a few intermediate values need to be thrown away.
*/
bool i2cReadRegister(uint8_t addr, uint8_t reg, uint8_t *value, uint16_t count);
/**
* i2cWrite - Writes the specified number of data bytes to the specified 7-bit I2C address.
* Returns true if successful or false if failed. If only smoe bytes could be written, false
* is still returned.
*
* The I2C address should be right-aligned; the R/W bit is automatically supplied.
*
* Since most I2C devices use an 8-bit register architecture, this method is mostly useful for
* setting the register position (most devices remember the last-used address) or writing a
* sequence of bytes to one register address using an auto-increment feature. In these cases,
* the first byte written from the data buffer should have the register address to use.
*/
bool i2cWrite(uint8_t addr, uint8_t *data, uint16_t count);
/**
* i2cWriteRegister - Writes the specified data byte to a register address on the specified
* 7-bit I2C address. Returns true if successful or false if failed.
*
* The I2C address should be right-aligned; the R/W bit is automatically supplied.
*
* Only one byte can be written to each register address using this method. While useful for
* the vast majority of I2C operations, writing multiple bytes requires the i2cWrite method.
*/
bool i2cWriteRegister(uint8_t addr, uint8_t reg, uint16_t value);
/**
* PROS_FILE is an integer referring to a stream for the standard I/O functions.
*
* PROS_FILE * is the standard library method of referring to a file pointer, even though there is
* actually nothing there.
*/
typedef int PROS_FILE;
#ifndef FILE
/**
* For convenience, FILE is defined as PROS_FILE if it wasn't already defined. This provides
* backwards compatability with PROS, but also allows libraries such as newlib to be incorporated
* into PROS projects. If you're not using C++/newlib, you can disregard this and just use FILE.
*/
#define FILE PROS_FILE
#endif
/**
* Bit mask for usartInit() for 8 data bits (typical)
*/
#define SERIAL_DATABITS_8 0x0000
/**
* Bit mask for usartInit() for 9 data bits
*/
#define SERIAL_DATABITS_9 0x1000
/**
* Bit mask for usartInit() for 1 stop bit (typical)
*/
#define SERIAL_STOPBITS_1 0x0000
/**
* Bit mask for usartInit() for 2 stop bits
*/
#define SERIAL_STOPBITS_2 0x2000
/**
* Bit mask for usartInit() for No parity (typical)
*/
#define SERIAL_PARITY_NONE 0x0000
/**
* Bit mask for usartInit() for Even parity
*/
#define SERIAL_PARITY_EVEN 0x0400
/**
* Bit mask for usartInit() for Odd parity
*/
#define SERIAL_PARITY_ODD 0x0600
/**
* Specifies the default serial settings when used in usartInit()
*/
#define SERIAL_8N1 0x0000
/**
* Initialize the specified serial interface with the given connection parameters.
*
* I/O to the port is accomplished using the "standard" I/O functions such as fputs(),
* fprintf(), and fputc().
*
* Re-initializing an open port may cause loss of data in the buffers. This routine may be
* safely called from initializeIO() or when the scheduler is paused. If I/O is attempted on a
* serial port which has never been opened, the behavior will be the same as if the port had
* been disabled.
*
* @param usart the port to open, either "uart1" or "uart2"
* @param baud the baud rate to use from 2400 to 1000000 baud
* @param flags a bit mask combination of the SERIAL_* flags specifying parity, stop, and data
* bits
*/
void usartInit(PROS_FILE *usart, unsigned int baud, unsigned int flags);
/**
* Disables the specified USART interface.
*
* Any data in the transmit and receive buffers will be lost. Attempts to read from the port
* when it is disabled will deadlock, and attempts to write to it may deadlock depending on
* the state of the buffer.
*
* @param usart the port to close, either "uart1" or "uart2"
*/
void usartShutdown(PROS_FILE *usart);
// -------------------- Character input and output --------------------
/**
* The standard output stream uses the PC debug terminal.
*/
#define stdout ((PROS_FILE *)3)
/**
* The standard input stream uses the PC debug terminal.
*/
#define stdin ((PROS_FILE *)3)
/**
* UART 1 on the Cortex; must be opened first using usartInit().
*/
#define uart1 ((PROS_FILE *)1)
/**
* UART 2 on the Cortex; must be opened first using usartInit().
*/
#define uart2 ((PROS_FILE *)2)
#ifndef EOF
/**
* EOF is a value evaluating to -1.
*/
#define EOF ((int)-1)
#endif
#ifndef SEEK_SET
/**
* SEEK_SET is used in fseek() to denote an absolute position in bytes from the start of the
* file.
*/
#define SEEK_SET 0
#endif
#ifndef SEEK_CUR
/**
* SEEK_CUR is used in fseek() to denote an relative position in bytes from the current file
* location.
*/
#define SEEK_CUR 1
#endif
#ifndef SEEK_END
/**
* SEEK_END is used in fseek() to denote an absolute position in bytes from the end of the
* file. The offset will most likely be negative in this case.
*/
#define SEEK_END 2
#endif
/**
* Closes the specified file descriptor. This function does not work on communication ports;
* use usartShutdown() instead.
*
* @param stream the file descriptor to close from fopen()
*/
void fclose(PROS_FILE *stream);
/**
* Returns the number of characters that can be read without blocking (the number of
* characters available) from the specified stream. This only works for communication ports and
* files in Read mode; for files in Write mode, 0 is always returned.
*
* This function may underestimate, but will not overestimate, the number of characters which
* meet this criterion.
*
* @param stream the stream to read (stdin, uart1, uart2, or an open file in Read mode)
* @return the number of characters which meet this criterion; if this number cannot be
* determined, returns 0
*/
int fcount(PROS_FILE *stream);
/**
* Delete the specified file if it exists and is not currently open.
*
* The file will actually be erased from memory on the next re-boot. A physical power cycle is
* required to purge deleted files and free their allocated space for new files to be written.
* Deleted files are still considered inaccessible to fopen() in Read mode.
*
* @param file the file name to erase
* @return 0 if the file was deleted, or 1 if the file could not be found
*/
int fdelete(const char *file);
/**
* Checks to see if the specified stream is at its end. This only works for communication ports
* and files in Read mode; for files in Write mode, 1 is always returned.
*
* @param stream the channel to check (stdin, uart1, uart2, or an open file in Read mode)
* @return 0 if the stream is not at EOF, or 1 otherwise.
*/
int feof(PROS_FILE *stream);
/**
* Flushes the data on the specified file channel open in Write mode. This function has no
* effect on a communication port or a file in Read mode, as these streams are always flushed as
* quickly as possible by the kernel.
*
* Successful completion of an fflush function on a file in Write mode cannot guarantee that
* the file is vaild until fclose() is used on that file descriptor.
*
* @param stream the channel to flush (an open file in Write mode)
* @return 0 if the data was successfully flushed, EOF otherwise
*/
int fflush(PROS_FILE *stream);
/**
* Reads and returns one character from the specified stream, blocking until complete.
*
* Do not use fgetc() on a VEX LCD port; deadlock may occur.
*
* @param stream the stream to read (stdin, uart1, uart2, or an open file in Read mode)
* @return the next character from 0 to 255, or -1 if no character can be read
*/
int fgetc(PROS_FILE *stream);
/**
* Reads a string from the specified stream, storing the characters into the memory at str.
* Characters will be read until the specified limit is reached, a new line is found, or the
* end of file is reached.
*
* If the stream is already at end of file (for files in Read mode), NULL will be returned;
* otherwise, at least one character will be read and stored into str.
*
* @param str the location where the characters read will be stored
* @param num the maximum number of characters to store; at most (num - 1) characters will be
* read, with a null terminator ('\0') automatically appended
* @param stream the channel to read (stdin, uart1, uart2, or an open file in Read mode)
* @return str, or NULL if zero characters could be read
*/
char* fgets(char *str, int num, PROS_FILE *stream);
/**
* Opens the given file in the specified mode. The file name is truncated to eight characters.
* Only four files can be in use simultaneously in any given time, with at most one of those
* files in Write mode. This function does not work on communication ports; use usartInit()
* instead.
*
* mode can be "r" or "w". Due to the nature of the VEX Cortex memory, the "r+", "w+", and "a"
* modes are not supported by the file system.
*
* Opening a file that does not exist in Read mode will fail and return NULL, but opening a new
* file in Write mode will create it if there is space. Opening a file that already exists in
* Write mode will destroy the contents and create a new blank file if space is available.
*
* There are important considerations when using of the file system on the VEX Cortex. Reading
* from files is safe, but writing to files should only be performed when robot actuators have
* been stopped. PROS will attempt to continue to handle events during file writes, but most
* user tasks cannot execute during file writing. Powering down the VEX Cortex mid-write may
* cause file system corruption.
*
* @param file the file name
* @param mode the file mode
* @return a file descriptor pointing to the new file, or NULL if the file could not be opened
*/
PROS_FILE * fopen(const char *file, const char *mode);
/**
* Prints the simple string to the specified stream.
*
* This method is much, much faster than fprintf() and does not add a new line like fputs().
* Do not use fprint() on a VEX LCD port. Use lcdSetText() instead.
*
* @param string the string to write
* @param stream the stream to write (stdout, uart1, uart2, or an open file in Write mode)
*/
void fprint(const char *string, PROS_FILE *stream);
/**
* Writes one character to the specified stream.
*
* Do not use fputc() on a VEX LCD port. Use lcdSetText() instead.
*
* @param value the character to write (a value of type "char" can be used)
* @param stream the stream to write (stdout, uart1, uart2, or an open file in Write mode)
* @return the character written
*/
int fputc(int value, PROS_FILE *stream);
/**
* Behaves the same as the "fprint" function, and appends a trailing newline ("\n").
*
* Do not use fputs() on a VEX LCD port. Use lcdSetText() instead.
*
* @param string the string to write
* @param stream the stream to write (stdout, uart1, uart2, or an open file in Write mode)
* @return the number of characters written, excluding the new line
*/
int fputs(const char *string, PROS_FILE *stream);
/**