diff --git a/src/Arduino_MachineControl.h b/src/Arduino_MachineControl.h index bfb8b0c..738945a 100644 --- a/src/Arduino_MachineControl.h +++ b/src/Arduino_MachineControl.h @@ -16,25 +16,50 @@ namespace machinecontrol { +/** + * The RTDClass allows enabling and selecting the different temperature sensor inputs + * (RTD and thermocouples) + */ class RTDClass { public: + + /** + * Select the input channel to be read (3 channels available) + * + * @param channel (0-2) + */ void selectChannel(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 + */ void enableTC() { 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 + */ void enableRTD() { rtd_th = 1; digitalWrite(PI_0, HIGH); digitalWrite(PA_6, LOW); } + + /** + * Disable Chip select for both RTD and thermocouple digital converters. + * + */ void disableCS() { digitalWrite(PI_0, HIGH); digitalWrite(PA_6, HIGH); @@ -52,9 +77,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. + */ class COMMClass { public: // to be tested: check if can be made a big pin initialization + + /** + * Shutdown RS485 and CAN LEDs + */ void init() { //SHUTDOWN OF RS485 LEDS digitalWrite(PA_0, LOW); @@ -64,9 +98,21 @@ class COMMClass { digitalWrite(PH_13, LOW); } + /** + * Set the CAN transceiver in Normal mode. In this mode, the transceiver + * can transmit and receive data via the bus lines CANH and CANL. + */ void enableCAN() { 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. + */ void disableCAN() { can_disable = 1; } @@ -96,8 +142,18 @@ extern COMMClass comm_protocols; #define ch2_in3 ch_in[10] #define ch2_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. + */ class AnalogInClass { 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_t read(int channel) { uint16_t value = 0; switch (channel) { @@ -117,6 +173,10 @@ class AnalogInClass { return value; } + /** + * Configure the input resistor dividers to have a ratio of 0.28. + * Maximum input voltage is 10V. + */ void set0_10V() { ch0_in1 = 1; ch0_in2 = 1; @@ -134,6 +194,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. + */ void set4_20mA() { ch0_in1 = 1; ch0_in2 = 0; @@ -151,6 +215,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) + */ void setNTC() { ch0_in1 = 0; ch0_in2 = 0; @@ -195,6 +263,12 @@ extern AnalogInClass analog_in; class AnalogOutClass { public: + + /** + * Set output voltage value (PWM) + * @param index select channel + * @param voltage desired output voltage (max 10.5V) + */ void write(int index, float voltage) { if (voltage < 0) { voltage = 0; @@ -215,6 +289,12 @@ class AnalogOutClass { break; } } + + /** + * Set the PWM period (frequency) + * @param index select channel + * @param period integer for selecting the period in ms + */ void period_ms(int index, uint8_t period) { switch (index) { case 0: @@ -257,11 +337,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. + */ class EncoderClass { 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) { case 0: @@ -286,14 +376,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. + */ class ProgrammableDIOClass : public ArduinoIOExpanderClass { public: + + /** + * Test connection with the IOExpander and set all the pins to the default mode. + * @return true if OK, false if fault + */ bool init() { return begin(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. + */ void setLatch() { 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. + */ void setRetry() { prog_latch_retry = 1; } @@ -304,20 +415,48 @@ class ProgrammableDIOClass : public ArduinoIOExpanderClass { extern ProgrammableDIOClass digital_programmables; +/** + * The DigitalOutputClass is used to interface with the IO Expander and + * set the digital outputs. + */ class DigitalOutputsClass { 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) + */ void setAll(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) + */ void set(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. + */ void setLatch() { 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. + */ void setRetry() { dig_out_latch_retry = 1; } @@ -336,6 +475,10 @@ extern DigitalOutputsClass digital_outputs; class ProgrammableDINClass : public ArduinoIOExpanderClass { public: + /** + * Test connection with the IOExpander and set all the pins to the default mode. + * @return true if OK, false if fault + */ bool init() { return begin(DIN_ADD); } @@ -343,7 +486,11 @@ class ProgrammableDINClass : public ArduinoIOExpanderClass { 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. + * + */ class RtcControllerClass : public PCF8563TClass { public: mbed::DigitalIn int_pin = mbed::DigitalIn(PB_9,PullUp); @@ -354,21 +501,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). + */ class USBClass { 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 + */ void init(const tusbh_class_reg_t *class_table) { usb.Init(USB_CORE_ID_FS, class_table); } + /** + * Enable power to USBA VBUS. + */ void powerEnable() { power = 0; } + /** + * Disable power to USBA VBUS. + */ void powerDisable() { 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 + */ bool vflagRead() { return usbflag; } diff --git a/src/utility/RTC/PCF8563T.cpp b/src/utility/RTC/PCF8563T.cpp index 7998a9d..c7c6f76 100644 --- a/src/utility/RTC/PCF8563T.cpp +++ b/src/utility/RTC/PCF8563T.cpp @@ -28,7 +28,7 @@ #define PCF8563T_MONTHS_REG 0x07 #define PCF8563T_YEARS_REG 0x08 -// allarm management +// alarm management #define PCF8563T_MINUTE_ALARM_REG 0x09 #define PCF8563T_MINUTE_ALARM_AE_M_MASK 0x80 #define PCF8563T_MINUTE_ALARM_ON 0x7F @@ -49,10 +49,20 @@ #define PCF8563T_STATUS_2_CLEAR_INT 0xF7 #define PCF8563T_STATUS_2_INT_OFF 0x7d +/** + * Object constructor + * + */ PCF8563TClass::PCF8563TClass() { } +/** + * Start the communication with the RTC + * Initialize I2C (Wire1) bus and check if the chip is connected by sending an ACK on the I2C bus. + * @return true if the RTC Controller is on the I2C bus, false if it is not. + * + */ bool PCF8563TClass::begin() { Wire1.begin(); // join i2c bus @@ -64,12 +74,22 @@ bool PCF8563TClass::begin() return false; } +/** + * Set Year number's value + * Save an unsigned byte with the Year's value + * @param years Year's unsigned byte + */ void PCF8563TClass::setYears(uint8_t years) { uint8_t dec = years / 10; uint8_t unit = years - (dec * 10); writeByte(PCF8563T_YEARS_REG, ((dec << 4) + unit)); } +/** + * Set Month number's value + * Save an unsigned byte with the Month's value + * @param months Month's unsigned byte (0 to 12) + */ void PCF8563TClass::setMonths(uint8_t months) { uint8_t offset = 0; if (months > 9) { @@ -78,35 +98,65 @@ void PCF8563TClass::setMonths(uint8_t months) { writeByte(PCF8563T_MONTHS_REG, months + offset); } +/** + * Set Day number's value + * Save an unsigned byte with the Day's value + * @param days day's unsigned byte + */ void PCF8563TClass::setDays(uint8_t days) { uint8_t dec = days / 10; uint8_t unit = days - (dec * 10); writeByte(PCF8563T_DAYS_REG, ((dec << 4) + unit)); } +/** + * Set Hour(s) number's value + * Save an unsigned byte with the Hour(s) value + * @param hours hour unsigned byte (0 - 23) + */ void PCF8563TClass::setHours(uint8_t hours) { uint8_t dec = hours / 10; uint8_t unit = hours - (dec * 10); writeByte(PCF8563T_HOURS_REG, ((dec << 4) + unit)); //check formula on datasheet val + 6 * (val / 10) } +/** + * Set Minute(s) number's value + * Save an unsigned byte with the Minute(s) value + * @param minutes minute unsigned byte (0-60) + */ void PCF8563TClass::setMinutes(uint8_t minutes) { uint8_t dec = minutes / 10; uint8_t unit = minutes - (dec * 10); writeByte(PCF8563T_MINUTES_REG, ((dec << 4) + unit)); } +/** + * Set Second(s) number's value + * Save an unsigned byte with the Second(s) value + * @param seconds Second(s) unsigned byte (0-60) + */ void PCF8563TClass::setSeconds(uint8_t seconds) { uint8_t dec = seconds / 10; uint8_t unit = seconds - (dec * 10); writeByte(PCF8563T_VL_SECONDS_REG, ((dec << 4) + unit)); } +/** + * Get Year(s) number's value + * Get unsigned byte with the Year(s) value + * @return byte with Year(s) value + */ uint8_t PCF8563TClass::getYears() { uint8_t years = readByte(PCF8563T_YEARS_REG); return (years & 0x0F) + ((years >> 4)*10); } +/** + * Get Month(s) month's value + * Get unsigned byte with the month(s) value + * @return byte with Month(s) value + */ uint8_t PCF8563TClass::getMonths() { uint8_t months = readByte(PCF8563T_MONTHS_REG) & 0x1F; if(months > 9) { @@ -116,27 +166,50 @@ uint8_t PCF8563TClass::getMonths() { } } +/** + * Get Day(s) number's value + * Get unsigned byte with the Day(s) value + * @return byte with Day(s) value + */ uint8_t PCF8563TClass::getDays() { uint8_t days = readByte(PCF8563T_DAYS_REG); return (days & 0x0F) + ((days >> 4)*10); } +/** + * Get Hour(s) number's value + * Get unsigned byte with the Hour(s) value + * @return byte with Hour(s) value + */ uint8_t PCF8563TClass::getHours() { uint8_t hours = readByte(PCF8563T_HOURS_REG) & 0x3F; return (hours & 0x0F) + ((hours >> 4)*10); } +/** + * Get Minute(s) number's value + * Get unsigned byte with the Minute(s) value + * @return byte with Minute(s) value + */ uint8_t PCF8563TClass::getMinutes() { uint8_t minutes = (readByte(PCF8563T_MINUTES_REG)) & 0x7F ; return (minutes & 0x0F) + ((minutes >> 4)*10); } +/** + * Get Second(s) number's value + * Get unsigned byte with the Second(s) value + * @return byte with Second(s) value + */ uint8_t PCF8563TClass::getSeconds() { uint8_t seconds = readByte(PCF8563T_VL_SECONDS_REG) & 0x7F; return (seconds & 0x0F) + ((seconds >> 4)*10); } - +/** + * Set time Epoch format + * + */ void PCF8563TClass::setEpoch() { struct tm time; time.tm_sec = getSeconds(); @@ -150,6 +223,12 @@ void PCF8563TClass::setEpoch() { set_time(seconds); } +/** + * Set time with Epoch format + * + * + * @param seconds number of seconds (time_t type) + */ void PCF8563TClass::setEpoch(time_t seconds) { struct tm time; _rtc_localtime(seconds, &time, RTC_FULL_LEAP_YEAR_SUPPORT); @@ -163,7 +242,19 @@ void PCF8563TClass::setEpoch(time_t seconds) { set_time(seconds); } - +/** + * Set time with Epoch format + * + * Convert the input values to Epoch format + * example: Tue, 06 Jul 2021 11:55:27 GMT -> 1625572527 + * + * @param years number of years + * @param mohths number of months + * @param days number of days + * @param hours number of hours + * @param minutes number of minutes + * @param seconds number of seconds + */ void PCF8563TClass::setEpoch(uint8_t years, uint8_t months, uint8_t days, uint8_t hours, uint8_t minutes, uint8_t seconds) { struct tm time; time_t utcsec; @@ -179,6 +270,15 @@ void PCF8563TClass::setEpoch(uint8_t years, uint8_t months, uint8_t days, uint8_ set_time(utcsec); } +/** + * Get epoch number + * Convert real time to difference between actual time and Epoch(Unix time) + * Saved into time_t type + * + * example: 1625572527 -> Tue, 06 Jul 2021 11:55:27 GMT + * + * @return number of seconds after Unix time (time_t type) + */ time_t PCF8563TClass::getEpoch() { struct tm time; time_t seconds; @@ -194,18 +294,35 @@ time_t PCF8563TClass::getEpoch() { return seconds; } +/** + * Enable alarm + * + */ void PCF8563TClass::enableAlarm() { writeByte(PCF8563T_STATUS_2_REG, (readByte(PCF8563T_STATUS_2_REG) & PCF8563T_STATUS_2_CLEAR_INT) | PCF8563T_STATUS_2_AIE_MASK); } +/** + * Disable alarm + * + */ void PCF8563TClass::disableAlarm() { writeByte(PCF8563T_STATUS_2_REG, (readByte(PCF8563T_STATUS_2_REG) & PCF8563T_STATUS_2_INT_OFF)); } +/** + * Clear alarm status + * + */ void PCF8563TClass::clearAlarm() { writeByte(PCF8563T_STATUS_2_REG, (readByte(PCF8563T_STATUS_2_REG) & PCF8563T_STATUS_2_CLEAR_INT) | PCF8563T_STATUS_2_AIE_MASK); } +/** + * Set alarm's minute + * + * @param minutes minute(s) value for the Alarm (byte type) + */ void PCF8563TClass::setMinuteAlarm(uint8_t minutes) { uint8_t dec = minutes / 10; uint8_t unit = minutes - (dec * 10); @@ -213,10 +330,19 @@ void PCF8563TClass::setMinuteAlarm(uint8_t minutes) { writeByte(PCF8563T_MINUTE_ALARM_REG , min_alarm); } +/** + * Disable and clear the minute of the Alarm + * + */ void PCF8563TClass::disableMinuteAlarm() { writeByte(PCF8563T_MINUTE_ALARM_REG, readByte(PCF8563T_MINUTE_ALARM_REG) | PCF8563T_MINUTE_ALARM_AE_M_MASK); } +/** + * Set Alarm's hour + * + * @param hours hour(s) value for the Alarm (byte type) + */ void PCF8563TClass::setHourAlarm(uint8_t hours) { uint8_t dec = hours / 10; uint8_t unit = hours - (dec * 10); @@ -224,10 +350,19 @@ void PCF8563TClass::setHourAlarm(uint8_t hours) { writeByte(PCF8563T_HOURS_REG, hour_alarm); //check formula on datasheet val + 6 * (val / 10) } +/** + * Disable and clear the hour of the Alarm + * + */ void PCF8563TClass::disableHourAlarm() { writeByte(PCF8563T_HOUR_ALARM_REG, readByte(PCF8563T_HOUR_ALARM_REG) | PCF8563T_HOUR_ALARM_AE_H_MASK); } +/** + * Set Alarm's day + * + * @param days day value for the Alarm (byte type) + */ void PCF8563TClass::setDayAlarm(uint8_t days) { uint8_t dec = days / 10; uint8_t unit = days - (dec * 10); @@ -235,6 +370,10 @@ void PCF8563TClass::setDayAlarm(uint8_t days) { writeByte(PCF8563T_DAY_ALARM_REG, day_alarm); } +/** + * Disable and clear the day of the Alarm + * + */ void PCF8563TClass::disableDayAlarm() { writeByte(PCF8563T_DAY_ALARM_REG, readByte(PCF8563T_DAY_ALARM_REG) | PCF8563T_DAY_ALARM_AE_D_MASK ); }