Skip to content
This repository was archived by the owner on Feb 28, 2024. It is now read-only.

Commit b64da1d

Browse files
author
ErnestoELC
committed
added javadox documentation for Arduino_MachineControl.h
1 parent 7cc75c9 commit b64da1d

File tree

1 file changed

+173
-4
lines changed

1 file changed

+173
-4
lines changed

src/Arduino_MachineControl.h

Lines changed: 173 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,25 +16,50 @@
1616

1717
namespace machinecontrol {
1818

19+
/**
20+
* The RTDClass allow enabling and selecting the different temperature sensor inputs
21+
* (RTD and thermocouples)
22+
*/
1923
class RTDClass {
2024
public:
25+
26+
/**
27+
* Select the input channel to be read (3 channels available)
28+
*
29+
* @param channel (0-2)
30+
*/
2131
void selectChannel(int channel) {
2232
for (int i=0; i<3; i++) {
2333
ch_sel[i] = (i == channel ? 1 : 0);
2434
}
2535
delay(150);
2636
}
37+
38+
/**
39+
* Enable the CS of the Thermocouple to digital converter
40+
* Disable the CS for the RTD to digital converter
41+
*/
2742
void enableTC() {
2843
rtd_th = 0;
2944
digitalWrite(PI_0, LOW);
3045
digitalWrite(PA_6, HIGH);
3146
}
47+
48+
/**
49+
* Enable the CS of the RDT to digital converter.
50+
* Disable the CS of the Thermocouple to digital converter
51+
*/
3252
void enableRTD() {
3353
rtd_th = 1;
3454
digitalWrite(PI_0, HIGH);
3555
digitalWrite(PA_6, LOW);
3656

3757
}
58+
59+
/**
60+
* Disable Chip select for both RTD and thermo couple digital converters.
61+
*
62+
*/
3863
void disableCS() {
3964
digitalWrite(PI_0, HIGH);
4065
digitalWrite(PA_6, HIGH);
@@ -52,9 +77,18 @@ extern RTDClass temp_probes;
5277

5378
static mbed::CAN _can(PB_8, PH_13);
5479

80+
81+
/**
82+
* The COMMClass is used to initialize the CAN and RS485 LEDs and
83+
* establish the power mode of the CAN bus.
84+
*/
5585
class COMMClass {
5686
public:
5787
// to be tested: check if can be made a big pin initialization
88+
89+
/**
90+
* Shutdown RS485 and CAN LEDS
91+
*/
5892
void init() {
5993
//SHUTDOWN OF RS485 LEDS
6094
digitalWrite(PA_0, LOW);
@@ -64,9 +98,21 @@ class COMMClass {
6498
digitalWrite(PH_13, LOW);
6599
}
66100

101+
/**
102+
* Set the CAN transciever in Normal mode. In this mode, the transceiver
103+
* can transmit and receive data via the bus lines CANH and CANL.
104+
*/
67105
void enableCAN() {
68106
can_disable = 0;
69107
}
108+
109+
/**
110+
* Set the CAN transciever in standby (low power) mode. In this mode the
111+
* transceiver will not be able to transmit or correctly receive data via the bus lines.
112+
* The wake-up filter on the output of the low-power receiver does not latch bus dominant states,
113+
* but ensures that only bus dominant and bus recessive states that persist longer than tfltr(wake)
114+
* bus are reflected on pin RXD.
115+
*/
70116
void disableCAN() {
71117
can_disable = 1;
72118
}
@@ -96,8 +142,18 @@ extern COMMClass comm_protocols;
96142
#define ch2_in3 ch_in[10]
97143
#define ch2_in4 ch_in[11]
98144

145+
/**
146+
* The AnalogInClass is used to set the resistor configuration for the right type of analog sensor
147+
* i.e. NTC sensors, 4-10mA or 0-10V.
148+
*/
99149
class AnalogInClass {
100150
public:
151+
152+
/**
153+
* read the sampled voltage from the selected channel
154+
* @param channel integer for selecting the analog input (0, 1 or 2)
155+
* @return the analog value between 0.0 and 1.0 normalized to a 16-bit value (uint16_t)
156+
*/
101157
uint16_t read(int channel) {
102158
uint16_t value = 0;
103159
switch (channel) {
@@ -117,6 +173,10 @@ class AnalogInClass {
117173
return value;
118174
}
119175

176+
/**
177+
* Configure the input resistor deviders to have a ratio of 0.28.
178+
* Maximum input voltage is 10V.
179+
*/
120180
void set0_10V() {
121181
ch0_in1 = 1;
122182
ch0_in2 = 1;
@@ -134,6 +194,10 @@ class AnalogInClass {
134194
ch2_in4 = 1;
135195
}
136196

197+
/**
198+
* Enable a 120 ohm resitor to GND to convert the 4-20mA sensor currents to voltage.
199+
* Note: 24V are available from the carrier to power the 4-20mA sensors.
200+
*/
137201
void set4_20mA() {
138202
ch0_in1 = 1;
139203
ch0_in2 = 0;
@@ -151,6 +215,10 @@ class AnalogInClass {
151215
ch2_in4 = 0;
152216
}
153217

218+
/**
219+
* Enable a 100K resitor in series with the reference voltage.
220+
* The voltage sampled is the voltage division between the 100k resistor and the input resistor (NTC/PTC)
221+
*/
154222
void setNTC() {
155223
ch0_in1 = 0;
156224
ch0_in2 = 0;
@@ -284,6 +352,8 @@ class AnalogOutPWMClass {
284352
}
285353

286354
~AnalogOutPWMClass(){}
355+
356+
287357
void period_ms(int period) {
288358
sConfig_time_base.Mode = HRTIM_MODE_CONTINUOUS;
289359
sConfig_time_base.Period = period;
@@ -322,12 +392,20 @@ class AnalogOutPWMClass {
322392
HRTIM_CompareCfgTypeDef sConfig_compare;
323393
};
324394

325-
326395
extern AnalogOutPWMClass analopwm;
327396

328-
397+
/**
398+
* The AnalogOutClass allows configuring the specified channel with the right PWM duty cycle and
399+
* frequency
400+
*/
329401
class AnalogOutClass {
330402
public:
403+
404+
/**
405+
* Set output voltage value (PWM)
406+
* @param index select channel
407+
* @param voltage desired output voltage (max 10.5V)
408+
*/
331409
void write(int index, float voltage) {
332410
if (voltage < 0) {
333411
voltage = 0;
@@ -348,6 +426,12 @@ class AnalogOutClass {
348426
break;
349427
}
350428
}
429+
430+
/**
431+
* Set the PWM period (frequency)
432+
* @param index select channel
433+
* @param period integer for selecting the period in ms
434+
*/
351435
void period_ms(int index, uint8_t period) {
352436
switch (index) {
353437
case 0:
@@ -394,8 +478,16 @@ extern AnalogOutClass analog_out;
394478
static QEI _enc_0(PJ_8, PH_12, PH_11, 0);
395479
static QEI _enc_1(PC_13, PI_7, PJ_10, 0);
396480

481+
/**
482+
* The EncoderClass is a wrapper for manipulating Quadrature Encoder Interface devices.
483+
*/
397484
class EncoderClass {
398485
public:
486+
/**
487+
* returns the encoder variable depending on the index
488+
* @param index integer for selecting the encoder (0 or 1)
489+
* @return enc_0 for index = 0, enc_1 for index = 1
490+
*/
399491
QEI& operator[](int index) {
400492
switch (index) {
401493
case 0:
@@ -420,14 +512,35 @@ extern EncoderClass encoders;
420512
TODO: check if Wire and address are correct
421513
*/
422514

515+
516+
/**
517+
* The ProgrammableDIOClass is used to initialize the IOExpanders and configure the
518+
* thermal shutdown mode of the high side switches.
519+
*/
423520
class ProgrammableDIOClass : public ArduinoIOExpanderClass {
424521
public:
522+
523+
/**
524+
* Test connection with the IOExpander and set all the pins to the default mode.
525+
* @return True if OK, False if fault
526+
*/
425527
bool init() {
426528
return begin(IO_ADD);
427529
}
530+
531+
/**
532+
* Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in latch mode.
533+
* The output latches off when thermal shutdown occurs.
534+
*/
428535
void setLatch() {
429536
prog_latch_retry = 0;
430537
}
538+
539+
/**
540+
* Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in auto-retry mode.
541+
* The output automatically recovers when TJ < T(SD) – T(hys), but the current is limited to ICL(TSD)
542+
* to avoid repetitive thermal shutdown.
543+
*/
431544
void setRetry() {
432545
prog_latch_retry = 1;
433546
}
@@ -438,20 +551,48 @@ class ProgrammableDIOClass : public ArduinoIOExpanderClass {
438551
extern ProgrammableDIOClass digital_programmables;
439552

440553

554+
/**
555+
* The DigitalOutputClass is used to interface with the IO Expander and
556+
* set the digital outputs.
557+
*/
441558
class DigitalOutputsClass {
442559
public:
560+
561+
/**
562+
* Set all digital outputs at the same time.
563+
* @param val 8 bit integer to set all 8 channels. e.g:
564+
* Set all to HIGH -> val = 255 (0b11111111)
565+
* Set all to LOW -> val = 0 (0b00000000)
566+
*/
443567
void setAll(uint8_t val) {
444568
for (int i = 0; i < 8; i++) {
445569
out[i] = val & 0x1;
446570
val = val >> 1;
447571
}
448572
}
573+
574+
/**
575+
* Set a particular digital output
576+
* @param index digital output to be set
577+
* @param val set value (HIGH/LOW)
578+
*/
449579
void set(int index, bool val) {
450580
out[index] = val;
451581
}
582+
583+
/**
584+
* Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in latch mode.
585+
* The output latches off when thermal shutdown occurs.
586+
*/
452587
void setLatch() {
453588
dig_out_latch_retry = 0;
454589
}
590+
591+
/**
592+
* Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in auto-retry mode.
593+
* The output automatically recovers when TJ < T(SD) – T(hys), but the current is limited to ICL(TSD)
594+
* to avoid repetitive thermal shutdown.
595+
*/
455596
void setRetry() {
456597
dig_out_latch_retry = 1;
457598
}
@@ -470,14 +611,22 @@ extern DigitalOutputsClass digital_outputs;
470611

471612
class ProgrammableDINClass : public ArduinoIOExpanderClass {
472613
public:
614+
/**
615+
* Test connection with the IOExpander and set all the pins to the default mode.
616+
* @return True if OK, False if fault
617+
*/
473618
bool init() {
474619
return begin(DIN_ADD);
475620
}
476621
};
477622

478623
extern ProgrammableDINClass digital_inputs;
479624

480-
625+
/**
626+
* The RtcControllerClass is a wrapper for the PCF8563TClass() that is used to
627+
* set and get the time to/from the PCF8563T RTC.
628+
*
629+
*/
481630
class RtcControllerClass : public PCF8563TClass {
482631
public:
483632
mbed::DigitalIn int_pin = mbed::DigitalIn(PB_9,PullUp);
@@ -488,21 +637,41 @@ class RtcControllerClass : public PCF8563TClass {
488637
extern RtcControllerClass rtc_controller;
489638

490639

491-
640+
/**
641+
* The USB Class is used to enable/disable the power of the USBA (Host) and configure
642+
* the callbacks for the different host types (i.e. Keyboard, mouse, storage device etc).
643+
*/
492644
class USBClass {
493645
public:
646+
/**
647+
* Configures the USB host by providing the list of callbacks to support the behaviour
648+
* of the host (keyboard, mouse, storage device etc)
649+
*
650+
* @param class_table a pointer to the structure containing the list of callbacks
651+
*/
494652
void init(const tusbh_class_reg_t *class_table) {
495653
usb.Init(USB_CORE_ID_FS, class_table);
496654
}
497655

656+
/**
657+
* Enable power to USBA VBUS.
658+
*/
498659
void powerEnable() {
499660
power = 0;
500661
}
501662

663+
/**
664+
* Disable power to USBA VBUS.
665+
*/
502666
void powerDisable() {
503667
power = 1;
504668
}
505669

670+
/**
671+
* Flag to indicate overcurrent, overtemperature, or reverse−voltage conditions on the USBA VBUS.
672+
* Active−low open−drain output.
673+
* @return True if OK, False if fault
674+
*/
506675
bool vflagRead() {
507676
return usbflag;
508677
}

0 commit comments

Comments
 (0)