Diff: MAX11410.h

Revision:

35:8aa5dffe523d

Parent:

25:a2afb91c605a

--- a/MAX11410.h	Sun Sep 22 18:23:10 2019 -0700
+++ b/MAX11410.h	Mon Nov 11 23:30:04 2019 +0000
@@ -1,4 +1,4 @@
-// /*******************************************************************************
+// /*******************************************************************************
 // * Copyright (C) 2019 Maxim Integrated Products, Inc., All Rights Reserved.
 // *
 // * Permission is hereby granted, free of charge, to any person obtaining a
@@ -40,10 +40,15 @@
 // System Description = Device driver example
 // Device Name = MAX11410
 // Device Description = 1.9ksps, Low-Power, Serial SPI 24-Bit, 10-Channel, Differential/Single-Ended Input, SAR ADC
+// Device DeviceBriefDescription = 24-bit 1.9ksps Delta-Sigma ADC
 // Device Manufacturer = Maxim Integrated
 // Device PartNumber = MAX11410ATI+
 // Device RegValue_Width = DataWidth16bit_HL
 //
+// ADC MaxOutputDataRate = 1.9ksps
+// ADC NumChannels = 10
+// ADC ResolutionBits = 24
+//
 // SPI CS = ActiveLow
 // SPI FrameStart = CS
 // SPI CPOL = 0
@@ -59,8 +64,41 @@
 #ifndef __MAX11410_H__
 #define __MAX11410_H__
 
-// standard include for target platform
+// standard include for target platform -- Platform_Include_Boilerplate
 #include "mbed.h"
+// Platforms:
+//   - MAX32625MBED
+//      - supports mbed-os-5.11, requires USBDevice library
+//      - add https://developer.mbed.org/teams/MaximIntegrated/code/USBDevice/
+//      - remove max32630fthr library (if present)
+//      - remove MAX32620FTHR library (if present)
+//   - MAX32600MBED
+//      - remove max32630fthr library (if present)
+//      - remove MAX32620FTHR library (if present)
+//      - Windows 10 note:  Don't connect HDK until you are ready to load new firmware into the board.
+//   - NUCLEO_F446RE
+//      - remove USBDevice library
+//      - remove max32630fthr library (if present)
+//      - remove MAX32620FTHR library (if present)
+//   - NUCLEO_F401RE
+//      - remove USBDevice library
+//      - remove max32630fthr library (if present)
+//      - remove MAX32620FTHR library (if present)
+//   - MAX32630FTHR
+//      - #include "max32630fthr.h"
+//      - add http://os.mbed.org/teams/MaximIntegrated/code/max32630fthr/
+//      - remove MAX32620FTHR library (if present)
+//   - MAX32620FTHR
+//      - #include "MAX32620FTHR.h"
+//      - remove max32630fthr library (if present)
+//      - add https://os.mbed.com/teams/MaximIntegrated/code/MAX32620FTHR/
+//      - not tested yet
+//   - MAX32625PICO
+//      - remove max32630fthr library (if present)
+//      - remove MAX32620FTHR library (if present)
+//      - not tested yet
+//
+// end Platform_Include_Boilerplate
 
 // CODE GENERATOR: conditional defines
 // CODE GENERATOR: class declaration and docstrings
@@ -76,10 +114,43 @@
  * //---------- CODE GENERATOR: helloCppCodeList
  * @code
  * // CODE GENERATOR: example code includes
+ *
  * // example code includes
- * // standard include for target platform
+ * // standard include for target platform -- Platform_Include_Boilerplate
  * #include "mbed.h"
- * //#include "max32625.h"
+ * // Platforms:
+ * //   - MAX32625MBED
+ * //      - supports mbed-os-5.11, requires USBDevice library
+ * //      - add https://developer.mbed.org/teams/MaximIntegrated/code/USBDevice/
+ * //      - remove max32630fthr library (if present)
+ * //      - remove MAX32620FTHR library (if present)
+ * //   - MAX32600MBED
+ * //      - remove max32630fthr library (if present)
+ * //      - remove MAX32620FTHR library (if present)
+ * //      - Windows 10 note:  Don't connect HDK until you are ready to load new firmware into the board.
+ * //   - NUCLEO_F446RE
+ * //      - remove USBDevice library
+ * //      - remove max32630fthr library (if present)
+ * //      - remove MAX32620FTHR library (if present)
+ * //   - NUCLEO_F401RE
+ * //      - remove USBDevice library
+ * //      - remove max32630fthr library (if present)
+ * //      - remove MAX32620FTHR library (if present)
+ * //   - MAX32630FTHR
+ * //      - #include "max32630fthr.h"
+ * //      - add http://os.mbed.org/teams/MaximIntegrated/code/max32630fthr/
+ * //      - remove MAX32620FTHR library (if present)
+ * //   - MAX32620FTHR
+ * //      - #include "MAX32620FTHR.h"
+ * //      - remove max32630fthr library (if present)
+ * //      - add https://os.mbed.com/teams/MaximIntegrated/code/MAX32620FTHR/
+ * //      - not tested yet
+ * //   - MAX32625PICO
+ * //      - remove max32630fthr library (if present)
+ * //      - remove MAX32620FTHR library (if present)
+ * //      - not tested yet
+ * //
+ * // end Platform_Include_Boilerplate
  * #include "MAX11410.h"
  *
  * // example code board support
@@ -126,21 +197,101 @@
  * // example code declare device instance
  * MAX11410 g_MAX11410_device(spi, spi_cs, MAX11410::MAX11410_IC);
  *
+ * // CODE GENERATOR: example code for ADC: serial port declaration
+ * //--------------------------------------------------
+ * // Declare the Serial driver
+ * // default baud rate settings are 9600 8N1
+ * // install device driver from http://developer.mbed.org/media/downloads/drivers/mbedWinSerial_16466.exe
+ * // see docs https://docs.mbed.com/docs/mbed-os-handbook/en/5.5/getting_started/what_need/
+ * #if defined(TARGET_MAX32630)
+ *     #include "USBSerial.h"
+ * // Hardware serial port over DAPLink
+ * // The default baud rate for the DapLink UART is 9600
+ * //Serial DAPLINKserial(P2_1, P2_0);     // tx, rx
+ * //    #define HAS_DAPLINK_SERIAL 1
+ * // Virtual serial port over USB
+ * // The baud rate does not affect the virtual USBSerial UART.
+ * USBSerial serial;
+ * //--------------------------------------------------
+ * #elif defined(TARGET_MAX32625MBED)
+ *     #include "USBSerial.h"
+ * // Hardware serial port over DAPLink
+ * // The default baud rate for the DapLink UART is 9600
+ * //Serial DAPLINKserial(P2_1, P2_0);     // tx, rx
+ * //    #define HAS_DAPLINK_SERIAL 1
+ * // Virtual serial port over USB
+ * // The baud rate does not affect the virtual USBSerial UART.
+ * USBSerial serial;
+ * //--------------------------------------------------
+ * #elif defined(TARGET_MAX32600)
+ *     #include "USBSerial.h"
+ * // Hardware serial port over DAPLink
+ * // The default baud rate for the DapLink UART is 9600
+ * Serial DAPLINKserial(P1_1, P1_0);     // tx, rx
+ *     #define HAS_DAPLINK_SERIAL 1
+ * // Virtual serial port over USB
+ * // The baud rate does not affect the virtual USBSerial UART.
+ * USBSerial serial;
+ * //--------------------------------------------------
+ * #elif defined(TARGET_NUCLEO_F446RE) || defined(TARGET_NUCLEO_F401RE)
+ * Serial serial(SERIAL_TX, SERIAL_RX);     // tx, rx
+ * //--------------------------------------------------
+ * #else
+ * #if defined(SERIAL_TX)
+ * #warning "target not previously tested; guess serial pins are SERIAL_TX, SERIAL_RX..."
+ * Serial serial(SERIAL_TX, SERIAL_RX);     // tx, rx
+ * #elif defined(USBTX)
+ * #warning "target not previously tested; guess serial pins are USBTX, USBRX..."
+ * Serial serial(USBTX, USBRX);     // tx, rx
+ * #elif defined(UART_TX)
+ * #warning "target not previously tested; guess serial pins are UART_TX, UART_RX..."
+ * Serial serial(UART_TX, UART_RX);     // tx, rx
+ * #else
+ * #warning "target not previously tested; need to define serial pins..."
+ * #endif
+ * #endif
+ * //
+ * #include "CmdLine.h"
+ * CmdLine cmdLine(serial, "serial");
+ *
  * // example code main function
  * int main()
  * {
+ *     // CODE GENERATOR: example code: member function Init
+ *     g_MAX11410_device.Init();
+ *
  *     while (1)
  *     {
- *         // CODE GENERATOR: example code: member function Init
- *         g_MAX11410_device.Init();
+ *         // CODE GENERATOR: example code: has no member function REF
+ *         // CODE GENERATOR: example code for ADC: repeat-forever convert and print conversion result, one record per line
+ *         // CODE GENERATOR: ResolutionBits = 24
+ *         // CODE GENERATOR: FScode = None
+ *         // CODE GENERATOR: NumChannels = 10
+ *         while(1) { // this code repeats forever
+ *             // this code repeats forever
+ *             // CODE GENERATOR: example code: has no member function ScanStandardExternalClock
+ *             // CODE GENERATOR: example code: has no member function ReadAINcode
+ *             // CODE GENERATOR: example code: member function _TODO_MAX11410_Read_All_Voltages_
+ *             // Measure ADC channels in sequence from AIN0 to channelNumber_0_9.
+ *             // @param[in] g_MAX11410_device.channelNumber_0_15: AIN Channel Number
+ *             // @param[in] g_MAX11410_device.PowerManagement_0_2: 0=Normal, 1=AutoShutdown, 2=AutoStandby
+ *             // @param[in] g_MAX11410_device.chan_id_0_1: ADC_MODE_CONTROL.CHAN_ID
+ *             int channelId_0_9 = 9;
+ *             //g_MAX11410_device.channelNumber_0_15 = channelId_0_9;
+ *             //g_MAX11410_device.PowerManagement_0_2 = 0;
+ *             //g_MAX11410_device.chan_id_0_1 = 1;
+ *             //g_MAX11410_device.NumWords = g_MAX11410_device._TODO_MAX11410_Read_All_Voltages_();
  *
- *         // CODE GENERATOR: example code: has no member function REF
- *         // CODE GENERATOR: example code: has no member function CODE_LOAD
- *         // CODE GENERATOR: example code: has no member function CODEallLOADall
- *         // CODE GENERATOR: example code: has no member function CODEnLOADn
- *         // CODE GENERATOR: example code: has no member function ScanManual
- *         // CODE GENERATOR: example code: has no member function ReadAINcode
- *         wait(3.0);
+ *             // wait(3.0);
+ *             // CODE GENERATOR: print conversion result
+ *             // Use Arduino Serial Plotter to view output: Tools | Serial Plotter
+ *             cmdLine.serial().printf("%d", g_MAX11410_device.AINcode[0]);
+ *             for (int index = 1; index <= channelId_0_9; index++) {
+ *                 cmdLine.serial().printf(",%d", g_MAX11410_device.AINcode[index]);
+ *             }
+ *             cmdLine.serial().printf("\r\n");
+ *
+ *         } // this code repeats forever
  *     }
  * }
  * @endcode
@@ -1022,6 +1173,10 @@
      **************************************************************/
     ~MAX11410();
 
+    // CODE GENERATOR: Declare SPI diagnostic function pointer void onSPIprint()
+    /// Function pointer void f(size_t byteCount, uint8_t mosiData[], uint8_t misoData[])
+    Callback<void(size_t, uint8_t*, uint8_t*)> onSPIprint; //!< optional @ref onSPIprint SPI diagnostic function
+
     // CODE GENERATOR: spi_frequency setter declaration
     /// set SPI SCLK frequency
     void spi_frequency(int spi_sclk_Hz);
@@ -1033,10 +1188,10 @@
     /// reference voltage, in Volts
     double VRef;
 
-    /// shadow of register CMD_r011_1000_dddd_dddd_dddd_dddd_dxxx_dddd_STATUS
+    /// shadow of register status CMD_r011_1000_dddd_dddd_dddd_dddd_dxxx_dddd_STATUS
     uint32_t status;
 
-    /// shadow of register CMD_r011_0000_dddd_dddd_dddd_dddd_dddd_dddd_DATA0
+    /// shadow of register data0 CMD_r011_0000_dddd_dddd_dddd_dddd_dddd_dddd_DATA0
     uint32_t data0;
 
 // CODE GENERATOR: omit global g_MAX11410_device
@@ -1094,6 +1249,7 @@
 
 // CODE GENERATOR: class member function declarations
     //----------------------------------------
+    /// Menu item '!'
     /// Initialize device
     /// @return 1 on success; 0 on failure
     uint8_t Init(void);
@@ -1107,89 +1263,98 @@
     /// @return physical voltage corresponding to MAX11410 code.
     double VoltageOfCode(uint16_t value_u24);
 
+// CODE GENERATOR: looks like this is a register access function because 'regAdd'
+// CODE GENERATOR: looks like this is a 'write' register access function
+// CODE GENERATOR: looks like this is a register access function because 'regAdd'
+// CODE GENERATOR: looks like this is a 'write' register access function: omit this function from test menu
     //----------------------------------------
-    /// Write an 8-bit MAX11410 register
+    /// Write a MAX11410 register.
+    ///
+    /// CMD_1aaa_aaaa_REGISTER_READ bit is cleared 0 indicating a write operation.
+    ///
+    /// MAX11410 register length can be determined by function RegSize.
     ///
-    /// CMD_1aaa_aaaa_REGISTER_READ bit is cleared 0.
+    /// For 8-bit register size:
+    ///
+    ///     SPI 16-bit transfer
+    ///
+    ///     SPI MOSI = 0aaa_aaaa_dddd_dddd
     ///
-    /// SPI 16-bit transfer
+    ///     SPI MISO = xxxx_xxxx_xxxx_xxxx
+    ///
+    /// For 16-bit register size:
+    ///
+    ///     SPI 24-bit or 32-bit transfer
+    ///
+    ///     SPI MOSI = 0aaa_aaaa_dddd_dddd_dddd_dddd
     ///
-    /// SPI MOSI = 0aaa_aaaa_dddd_dddd
+    ///     SPI MISO = xxxx_xxxx_xxxx_xxxx_xxxx_xxxx
+    ///
+    /// For 24-bit register size:
     ///
-    /// SPI MISO = xxxx_xxxx_xxxx_xxxx
+    ///     SPI 32-bit transfer
+    ///
+    ///     SPI MOSI = 0aaa_aaaa_dddd_dddd_dddd_dddd_dddd_dddd
+    ///
+    ///     SPI MISO = xxxx_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx
     ///
     /// @return 1 on success; 0 on failure
-    uint8_t Write_8bit(MAX11410_CMD_enum_t regAddress, uint8_t regData);
+    uint8_t RegWrite(MAX11410_CMD_enum_t regAddress, uint32_t regData);
 
+// CODE GENERATOR: looks like this is a register access function because 'regAdd'
+// CODE GENERATOR: looks like this is a 'read' register access function
+// CODE GENERATOR: looks like this is a register access function because 'regAdd'
+// CODE GENERATOR: looks like this is a 'read' register access function: omit this function from test menu
     //----------------------------------------
     /// Read an 8-bit MAX11410 register
     ///
-    /// CMD_1aaa_aaaa_REGISTER_READ bit is set 1.
+    /// CMD_1aaa_aaaa_REGISTER_READ bit is set 1 indicating a read operation.
     ///
-    /// SPI 16-bit transfer
+    /// MAX11410 register length can be determined by function RegSize.
+    ///
+    /// For 8-bit register size:
     ///
-    /// SPI MOSI = 1aaa_aaaa_0000_0000
+    ///     SPI 16-bit transfer
+    ///
+    ///     SPI MOSI = 1aaa_aaaa_0000_0000
     ///
-    /// SPI MISO = xxxx_xxxx_dddd_dddd
+    ///     SPI MISO = xxxx_xxxx_dddd_dddd
+    ///
+    /// For 16-bit register size:
     ///
-    /// @return 1 on success; 0 on failure
-    uint8_t Read_8bit(MAX11410_CMD_enum_t regAddress, uint8_t* ptrRegData);
-
-    //----------------------------------------
-    /// Write a 16-bit MAX11410 register
+    ///     SPI 24-bit or 32-bit transfer
+    ///
+    ///     SPI MOSI = 1aaa_aaaa_0000_0000_0000_0000
+    ///
+    ///     SPI MISO = xxxx_xxxx_dddd_dddd_dddd_dddd
     ///
-    /// CMD_1aaa_aaaa_REGISTER_READ bit is cleared 0.
+    /// For 24-bit register size:
     ///
-    /// SPI 24-bit transfer
+    ///     SPI 32-bit transfer
     ///
-    /// SPI MOSI = 0aaa_aaaa_dddd_dddd_dddd_dddd
+    ///     SPI MOSI = 1aaa_aaaa_0000_0000_0000_0000_0000_0000
     ///
-    /// SPI MISO = xxxx_xxxx_xxxx_xxxx_xxxx_xxxx
+    ///     SPI MISO = xxxx_xxxx_dddd_dddd_dddd_dddd_dddd_dddd
+    ///
     ///
     /// @return 1 on success; 0 on failure
-    uint8_t Write_16bit(MAX11410_CMD_enum_t regAddress, uint16_t regData);
+    uint8_t RegRead(MAX11410_CMD_enum_t regAddress, uint32_t* ptrRegData);
 
+// CODE GENERATOR: looks like this is a register access function because 'regAdd'
+// CODE GENERATOR: looks like this is a 'size' register access function
     //----------------------------------------
-    /// Read a 16-bit MAX11410 register
-    ///
-    /// CMD_1aaa_aaaa_REGISTER_READ bit is set 1.
-    ///
-    /// SPI 24-bit transfer
-    ///
-    /// SPI MOSI = 1aaa_aaaa_0000_0000_0000_0000
-    ///
-    /// SPI MISO = xxxx_xxxx_dddd_dddd_dddd_dddd
-    ///
-    /// @return 1 on success; 0 on failure
-    uint8_t Read_16bit(MAX11410_CMD_enum_t regAddress, uint16_t* ptrRegData);
-
-    //----------------------------------------
-    /// Write a 24-bit MAX11410 register
-    ///
-    /// CMD_1aaa_aaaa_REGISTER_READ bit is cleared 0.
+    /// Return the size of a MAX11410 register
     ///
-    /// SPI 32-bit transfer
-    ///
-    /// SPI MOSI = 0aaa_aaaa_dddd_dddd_dddd_dddd_dddd_dddd
-    ///
-    /// SPI MISO = xxxx_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx_xxxx
-    ///
-    /// @return 1 on success; 0 on failure
-    uint8_t Write_24bit(MAX11410_CMD_enum_t regAddress, uint32_t regData);
+    /// @return 8 for 8-bit, 16 for 16-bit, 24 for 24-bit, else 0 for undefined register size
+    uint8_t RegSize(MAX11410_CMD_enum_t regAddress);
 
+// CODE GENERATOR: looks like this is a register access function because 'regAdd'
+// CODE GENERATOR: looks like this is a 'name' register access function
     //----------------------------------------
-    /// Read a 24-bit MAX11410 register
-    ///
-    /// CMD_1aaa_aaaa_REGISTER_READ bit is set 1.
-    ///
-    /// SPI 32-bit transfer
+    /// Return the name of a MAX11410 register
     ///
-    /// SPI MOSI = 1aaa_aaaa_0000_0000_0000_0000_0000_0000
-    ///
-    /// SPI MISO = xxxx_xxxx_dddd_dddd_dddd_dddd_dddd_dddd
-    ///
-    /// @return 1 on success; 0 on failure
-    uint8_t Read_24bit(MAX11410_CMD_enum_t regAddress, uint32_t* ptrRegData);
+    /// @return null-terminated constant C string containing register name or empty string
+    const char* RegName(MAX11410_CMD_enum_t regAddress);
 
     //----------------------------------------
     /// Configure Measurement for voltage input.
@@ -1214,6 +1379,15 @@
     uint8_t Configure_Voltage(MAX11410_AINP_SEL_enum_t channel_hi, MAX11410_AINN_SEL_enum_t channel_lo);
 
     //----------------------------------------
+    /// Measure ADC channels in sequence from AIN0 to channelNumber_0_9.
+    /// @param[in] channel_hi = channel high side
+    /// @param[in] channel_lo = channel low side
+    /// @post AINcode[index]: measurement
+    ///
+    /// @return 1 on success; 0 on failure
+    uint8_t _TODO_MAX11410_Read_All_Voltages_(MAX11410_AINP_SEL_enum_t channel_hi, MAX11410_AINN_SEL_enum_t channel_lo);
+
+    //----------------------------------------
     /// Trigger Measurement for voltage input.
     ///
     /// Example code for typical voltage measurement.