added javadox documentation for Arduino_MachineControl.h (#62)

* added javadox documentation for Arduino_MachineControl.h * RTC: Added javadoc comments * Apply suggestions from code review Accepted revision Co-authored-by: per1234 <[email protected]> * Update Arduino_MachineControl.h Co-authored-by: marqdevx <[email protected]> Co-authored-by: per1234 <[email protected]> Co-authored-by: marqdevx <[email protected]>

Author: 3 people

src/Arduino_MachineControl.h

@@ -17,25 +17,50 @@
 
 namespacemachinecontrol{
 
+/**
+ * The RTDClass allows enabling and selecting the different temperature sensor inputs
+ * (RTD and thermocouples)
+*/
 classRTDClass{
 public:
+
+/**
+ * Select the input channel to be read (3 channels available)
+ * 
+ * @param channel (0-2)
+*/
 voidselectChannel(int channel){
 for (int i=0; i<3; i++){
  ch_sel[i] = (i == channel ? 1 : 0);
  }
 delay(150);
  }
+
+/**
+ * Enable the CS of the Thermocouple to digital converter
+ * Disable the CS for the RTD to digital converter
+*/
 voidenableTC(){
  rtd_th = 0;
 digitalWrite(PI_0, LOW);
 digitalWrite(PA_6, HIGH);
  }
+
+/**
+ * Enable the CS of the RDT to digital converter. 
+ * Disable the CS of the Thermocouple to digital converter
+*/
 voidenableRTD(){
  rtd_th = 1;
 digitalWrite(PI_0, HIGH);
 digitalWrite(PA_6, LOW);
 
  }
+
+/**
+ * Disable Chip select for both RTD and thermocouple digital converters. 
+ * 
+*/
 voiddisableCS(){
 digitalWrite(PI_0, HIGH);
 digitalWrite(PA_6, HIGH);
@@ -53,9 +78,18 @@ extern RTDClass temp_probes;
 
 static mbed::CAN _can(PB_8, PH_13);
 
+
+/**
+ * The COMMClass is used to initialize the CAN and RS485 LEDs and 
+ * establish the power mode of the CAN bus. 
+*/
 classCOMMClass{
 public:
 // to be tested: check if can be made a big pin initialization
+
+/**
+ * Shutdown RS485 and CAN LEDs
+*/
 voidinit(){
 //SHUTDOWN OF RS485 LEDS
 digitalWrite(PinNameToIndex(PA_0), LOW);
@@ -73,9 +107,21 @@ class COMMClass{
 rs485Slew(false);
  }
 
+/**
+ * Set the CAN transceiver in Normal mode. In this mode, the transceiver 
+ * can transmit and receive data via the bus lines CANH and CANL.
+*/
 voidenableCAN(){
  can_disable = 0;
  }
+
+/**
+ * Set the CAN transceiver in standby (low power) mode. In this mode the
+ * transceiver will not be able to transmit or correctly receive data via the bus lines.
+ * The wake-up filter on the output of the low-power receiver does not latch bus dominant states,
+ * but ensures that only bus dominant and bus recessive states that persist longer than tfltr(wake)
+ * bus are reflected on pin RXD.
+*/
 voiddisableCAN(){
  can_disable = 1;
  }
@@ -118,8 +164,18 @@ extern COMMClass comm_protocols;
 #definech2_in3 ch_in[10]
 #definech2_in4 ch_in[11]
 
+/**
+ * The AnalogInClass is used to set the resistor configuration for the right type of analog sensor
+ * i.e. NTC sensors, 4-10mA or 0-10V. 
+*/
 classAnalogInClass{
 public:
+
+/**
+ * read the sampled voltage from the selected channel
+ * @param channel integer for selecting the analog input (0, 1 or 2)
+ * @return the analog value between 0.0 and 1.0 normalized to a 16-bit value (uint16_t)
+*/
 uint16_tread(int channel){
 uint16_t value = 0;
 switch (channel){
@@ -139,6 +195,10 @@ class AnalogInClass{
 return value;
  }
 
+/**
+ * Configure the input resistor dividers to have a ratio of 0.28.
+ * Maximum input voltage is 10V. 
+*/
 voidset0_10V(){
  ch0_in1 = 1;
  ch0_in2 = 1;
@@ -156,6 +216,10 @@ class AnalogInClass{
  ch2_in4 = 1;
  }
 
+/**
+ * Enable a 120 ohm resistor to GND to convert the 4-20mA sensor currents to voltage. 
+ * Note: 24V are available from the carrier to power the 4-20mA sensors. 
+*/
 voidset4_20mA(){
  ch0_in1 = 1;
  ch0_in2 = 0;
@@ -173,6 +237,10 @@ class AnalogInClass{
  ch2_in4 = 0;
  }
 
+/**
+ * Enable a 100K resistor in series with the reference voltage. 
+ * The voltage sampled is the voltage division between the 100k resistor and the input resistor (NTC/PTC) 
+*/
 voidsetNTC(){
  ch0_in1 = 0;
  ch0_in2 = 0;
@@ -217,6 +285,12 @@ extern AnalogInClass analog_in;
 
 classAnalogOutClass{
 public:
+
+/**
+ * Set output voltage value (PWM)
+ * @param index select channel
+ * @param voltage desired output voltage (max 10.5V)
+*/
 voidwrite(int index, float voltage){
 if (voltage < 0){
  voltage = 0;
@@ -237,6 +311,12 @@ class AnalogOutClass{
 break;
  }
  }
+
+/**
+ * Set the PWM period (frequency)
+ * @param index select channel
+ * @param period integer for selecting the period in ms
+*/
 voidperiod_ms(int index, uint8_t period){
 switch (index){
 case0:
@@ -279,11 +359,21 @@ extern AnalogOutClass analog_out;
  TODO: writeme 
  Use QEI library for mbed since it implements index pin
 */
+/**
+ * The EncoderClass is a wrapper for manipulating Quadrature Encoder Interface devices.
+*/
 classEncoderClass{
 public:
+/**
+ * returns the encoder variable depending on the index
+ * @param index integer for selecting the encoder (0 or 1)
+ * @return enc_0 for index = 0, enc_1 for index = 1
+*/
 EncoderClass()
  : enc_0{PJ_8, PH_12, PH_11, 0}
  , enc_1{PC_13, PI_7, PJ_10, 0}{};
+
+
  QEI& operator[](int index){
 switch (index){
 case0:
@@ -308,14 +398,35 @@ extern EncoderClass encoders;
  TODO: check if Wire and address are correct
 */
 
+
+/**
+ * The ProgrammableDIOClass is used to initialize the IOExpanders and configure the 
+ * thermal shutdown mode of the high side switches.
+*/
 classProgrammableDIOClass : publicArduinoIOExpanderClass{
 public:
+
+/**
+ * Test connection with the IOExpander and set all the pins to the default mode. 
+ * @return true if OK, false if fault
+*/
 boolinit(){
 returnbegin(IO_ADD);
  }
+
+/**
+ * Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in latch mode. 
+ * The output latches off when thermal shutdown occurs. 
+*/
 voidsetLatch(){
  prog_latch_retry = 0;
  }
+
+/**
+ * Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in auto-retry mode. 
+ * The output automatically recovers when TJ < T(SD) – T(hys), but the current is limited to ICL(TSD) 
+ * to avoid repetitive thermal shutdown. 
+*/
 voidsetRetry(){
  prog_latch_retry = 1;
  }
@@ -326,20 +437,48 @@ class ProgrammableDIOClass : public ArduinoIOExpanderClass{
 extern ProgrammableDIOClass digital_programmables;
 
 
+/**
+ * The DigitalOutputClass is used to interface with the IO Expander and
+ * set the digital outputs.
+*/
 classDigitalOutputsClass{
 public:
+
+/**
+ * Set all digital outputs at the same time. 
+ * @param val 8 bit integer to set all 8 channels. e.g:
+ * Set all to HIGH -> val = 255 (0b11111111)
+ * Set all to LOW -> val = 0 (0b00000000)
+*/
 voidsetAll(uint8_t val){
 for (int i = 0; i < 8; i++){
  out[i] = val & 0x1;
  val = val >> 1;
  }
  }
+
+/**
+ * Set a particular digital output
+ * @param index digital output to be set
+ * @param val set value (HIGH/LOW)
+*/
 voidset(int index, bool val){
  out[index] = val;
  }
+
+/**
+ * Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in latch mode. 
+ * The output latches off when thermal shutdown occurs. 
+*/
 voidsetLatch(){
  dig_out_latch_retry = 0;
  }
+
+/**
+ * Configures the thermal shutdown of the high-side switches (TPS4H160) to operate in auto-retry mode. 
+ * The output automatically recovers when TJ < T(SD) – T(hys), but the current is limited to ICL(TSD) 
+ * to avoid repetitive thermal shutdown. 
+*/
 voidsetRetry(){
  dig_out_latch_retry = 1;
  }
@@ -358,14 +497,22 @@ extern DigitalOutputsClass digital_outputs;
 
 classProgrammableDINClass : publicArduinoIOExpanderClass{
 public:
+/**
+ * Test connection with the IOExpander and set all the pins to the default mode. 
+ * @return true if OK, false if fault
+*/
 boolinit(){
 returnbegin(DIN_ADD);
  }
 };
 
 extern ProgrammableDINClass digital_inputs;
 
-
+/**
+ * The RtcControllerClass is a wrapper for the PCF8563TClass() that is used to 
+ * set and get the time to/from the PCF8563T RTC.
+ * 
+*/
 classRtcControllerClass : publicPCF8563TClass{
 public:
  mbed::DigitalIn int_pin = mbed::DigitalIn(PB_9,PullUp);
@@ -376,21 +523,41 @@ class RtcControllerClass : public PCF8563TClass{
 extern RtcControllerClass rtc_controller;
 
 
-
+/**
+ * The USB Class is used to enable/disable the power of the USBA (Host) and configure
+ * the callbacks for the different host types (i.e. Keyboard, mouse, storage device etc). 
+*/
 classUSBClass{
 public:
+/**
+ * Configures the USB host by providing the list of callbacks to support the behaviour
+ * of the host (keyboard, mouse, storage device etc)
+ * 
+ * @param class_table a pointer to the structure containing the list of callbacks 
+*/
 voidinit(consttusbh_class_reg_t *class_table){
  usb.Init(USB_CORE_ID_FS, class_table);
  }
 
+/**
+ * Enable power to USBA VBUS. 
+*/
 voidpowerEnable(){
  power = 0;
  }
 
+/**
+ * Disable power to USBA VBUS. 
+*/
 voidpowerDisable(){
  power = 1;
  }
 
+/**
+ * Flag to indicate overcurrent, overtemperature, or reverse−voltage conditions on the USBA VBUS. 
+ * Active−low open−drain output.
+ * @return true if OK, false if fault
+*/
 boolvflagRead(){
 return usbflag;
  }