SSInterface.h

00001 /***************************************************************************
00002 * Copyright (C) 2017 Maxim Integrated Products, Inc., All Rights Reserved.
00003 *
00004 * Permission is hereby granted, free of charge, to any person obtaining a
00005 * copy of this software and associated documentation files (the "Software"),
00006 * to deal in the Software without restriction, including without limitation
00007 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00008 * and/or sell copies of the Software, and to permit persons to whom the
00009 * Software is furnished to do so, subject to the following conditions:
00010 *
00011 * The above copyright notice and this permission notice shall be included
00012 * in all copies or substantial portions of the Software.
00013 *
00014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00015 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00017 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00018 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00019 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00020 * OTHER DEALINGS IN THE SOFTWARE.
00021 *
00022 * Except as contained in this notice, the name of Maxim Integrated
00023 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00024 * Products, Inc. Branding Policy.
00025 *
00026 * The mere transfer of this software does not imply any licenses
00027 * of trade secrets, proprietary technology, copyrights, patents,
00028 * trademarks, maskwork rights, or any other form of intellectual
00029 * property whatsoever. Maxim Integrated Products, Inc. retains all
00030 * ownership rights.
00031 ****************************************************************************
00032 */
00033 
00034 #ifndef _SSINTERFACE_H_
00035 #define _SSINTERFACE_H_
00036 
00037 #include "mbed.h"
00038 #include "MaximSensor.h"
00039 
00040 #define SS_PLATFORM_MAX3263X    "SmartSensor_MAX3263X"
00041 #define SS_PLATFORM_MAX32660    "SmartSensor_MAX32660"
00042 #define SS_BOOTLOADER_PLATFORM_MAX3263X    "Bootloader_MAX3263X"
00043 #define SS_BOOTLOADER_PLATFORM_MAX32660    "Bootloader_MAX32660"
00044 
00045 
00046 #define SS_I2C_8BIT_SLAVE_ADDR 0xAA
00047 #define SS_DEFAULT_CMD_SLEEP_MS 2
00048 #define SS_DUMP_REG_SLEEP_MS 100
00049 #define SS_ENABLE_SENSOR_SLEEP_MS 20
00050 
00051 #define SS_SENSORIDX_OS58   0x00
00052 #define SS_SENSORIDX_DT07   0x01
00053 #define SS_SENSORIDX_OT02   0x02
00054 #define SS_SENSORIDX_OS24   0x03
00055 #define SS_SENSORIDX_ACCEL  0x04
00056 
00057 #define SS_ALGOIDX_AGC  0x00
00058 #define SS_ALGOIDX_AEC  0x01
00059 #define SS_ALGOIDX_WHRM 0x02
00060 #define SS_ALGOIDX_ECG  0x03
00061 
00062 
00063 #define SS_FAM_R_STATUS     0x00
00064     #define SS_CMDIDX_STATUS    0x00
00065         #define SS_SHIFT_STATUS_ERR             0
00066         #define SS_MASK_STATUS_ERR              (0x07 << SS_SHIFT_STATUS_ERR)
00067         #define SS_SHIFT_STATUS_DATA_RDY        3
00068         #define SS_MASK_STATUS_DATA_RDY         (1 << SS_SHIFT_STATUS_DATA_RDY)
00069         #define SS_SHIFT_STATUS_FIFO_OUT_OVR    4
00070         #define SS_MASK_STATUS_FIFO_OUT_OVR     (1 << SS_SHIFT_STATUS_FIFO_OUT_OVR)
00071         #define SS_SHIFT_STATUS_FIFO_IN_OVR     5
00072         #define SS_MASK_STATUS_FIFO_IN_OVR      (1 << SS_SHIFT_STATUS_FIFO_IN_OVR)
00073 
00074 #define SS_FAM_W_MODE   0x01
00075 #define SS_FAM_R_MODE   0x02
00076     #define SS_CMDIDX_MODE  0x00
00077         #define SS_SHIFT_MODE_SHDN      0
00078         #define SS_MASK_MODE_SHDN       (1 << SS_SHIFT_MODE_SHDN)
00079         #define SS_SHIFT_MODE_RESET     1
00080         #define SS_MASK_MODE_RESET      (1 << SS_SHIFT_MODE_RESET)
00081         #define SS_SHIFT_MODE_FIFORESET 2
00082         #define SS_MASK_MODE_FIFORESET  (1 << SS_SHIFT_MODE_FIFORESET)
00083         #define SS_SHIFT_MODE_BOOTLDR   3
00084         #define SS_MASK_MODE_BOOTLDR    (1 << SS_SHIFT_MODE_BOOTLDR)
00085 
00086 #define SS_I2C_READ     0x03
00087 
00088 #define SS_FAM_W_COMMCHAN   0x10
00089 #define SS_FAM_R_COMMCHAN   0x11
00090     #define SS_CMDIDX_OUTPUTMODE    0x00
00091         #define SS_SHIFT_OUTPUTMODE_DATATYPE    0
00092         #define SS_MASK_OUTPUTMODE_DATATYPE     (0x03 << SS_SHIFT_OUTPUTMODE_DATATYPE)
00093             #define SS_DATATYPE_PAUSE               0
00094             #define SS_DATATYPE_RAW                 1
00095             #define SS_DATATYPE_ALGO                2
00096             #define SS_DATATYPE_BOTH                3
00097         #define SS_SHIFT_OUTPUTMODE_SC_EN       2
00098         #define SS_MASK_OUTPUTMODE_SC_EN        (1 << SS_SHIFT_OUTPUTMODE_SC_EN)
00099     #define SS_CMDIDX_FIFOAFULL     0x01
00100 
00101 #define SS_FAM_R_OUTPUTFIFO 0x12
00102     #define SS_CMDIDX_OUT_NUMSAMPLES    0x00
00103     #define SS_CMDIDX_READFIFO          0x01
00104 
00105 #define SS_FAM_R_INPUTFIFO  0x13
00106     #define SS_CMDIDX_SAMPLESIZE    0x00
00107     #define SS_CMDIDX_FIFOSIZE      0x01
00108     #define SS_CMDIDX_IN_NUMSAMPLES 0x02
00109 #define SS_FAM_W_INPUTFIFO  0x14
00110     #define SS_CMDIDN_WRITEFIFO     0x00
00111 
00112 #define SS_FAM_W_WRITEREG       0x40
00113 #define SS_FAM_R_READREG        0x41
00114 #define SS_FAM_R_REGATTRIBS     0x42
00115 #define SS_FAM_R_DUMPREG        0x43
00116 
00117 #define SS_FAM_W_SENSORMODE 0x44
00118 #define SS_FAM_R_SENSORMODE 0x45
00119 
00120 //TODO: Fill in known configuration parameters
00121 #define SS_FAM_W_ALGOCONFIG 0x50
00122 #define SS_FAM_R_ALGOCONFIG 0x51
00123 
00124 #define SS_FAM_W_ALGOMODE   0x52
00125 #define SS_FAM_R_ALGOMODE   0x53
00126 
00127 #define SS_FAM_W_EXTERNSENSORMODE   0x60
00128 #define SS_FAM_R_EXTERNSENSORMODE   0x61
00129 
00130 #define SS_FAM_R_SELFTEST    0x70
00131 
00132 #define SS_FAM_W_BOOTLOADER 0x80
00133     #define SS_CMDIDX_SETIV         0x00
00134     #define SS_CMDIDX_SETAUTH       0x01
00135     #define SS_CMDIDX_SETNUMPAGES   0x02
00136     #define SS_CMDIDX_ERASE         0x03
00137     #define SS_CMDIDX_SENDPAGE      0x04
00138 #define SS_FAM_R_BOOTLOADER 0x81
00139     #define SS_CMDIDX_BOOTFWVERSION 0x00
00140     #define SS_CMDIDX_PAGESIZE      0x01
00141 
00142 #define SS_FAM_R_IDENTITY   0xFF
00143     #define SS_CMDIDX_PLATTYPE      0x00
00144     #define SS_CMDIDX_PARTID        0x01
00145     #define SS_CMDIDX_REVID         0x02
00146     #define SS_CMDIDX_FWVERSION     0x03
00147     #define SS_CMDIDX_AVAILSENSORS  0x04
00148     #define SS_CMDIDX_DRIVERVER     0x05
00149     #define SS_CMDIDX_AVAILALGOS    0x06
00150     #define SS_CMDIDX_ALGOVER       0x07
00151 
00152 
00153 
00154 typedef enum {
00155     SS_SUCCESS=0x00,
00156 
00157     SS_ERR_COMMAND=0x01,
00158     SS_ERR_UNAVAILABLE=0x02,
00159     SS_ERR_DATA_FORMAT=0x03,
00160     SS_ERR_INPUT_VALUE=0x04,
00161 
00162     SS_ERR_BTLDR_GENERAL=0x80,
00163     SS_ERR_BTLDR_CHECKSUM=0x81,
00164 
00165     SS_ERR_UNKNOWN=0xFF
00166 } SS_STATUS;
00167 
00168 typedef enum {
00169     SS_PLAT_MAX3263X=0,
00170     SS_PLAT_MAX32660=1,
00171 } SS_PLAT_TYPE;
00172 
00173 //self test result masks
00174 #define FAILURE_COMM        0x01
00175 #define FAILURE_INTERRUPT   0x02
00176 
00177 #define SS_SMALL_BUF_SIZE 32
00178 #define SS_LARGE_BUF_SIZE 8224
00179 
00180 #define SS_RESET_TIME   10
00181 #define SS_STARTUP_TIME 1000
00182 
00183 #define SS_MAX_SUPPORTED_SENSOR_NUM 0xFE
00184 #define SS_MAX_SUPPORTED_ALGO_NUM   0xFE
00185 #define SS_MAX_SUPPORTED_MODE_NUM   0xFF
00186 
00187 typedef struct {
00188     int data_size;
00189     Callback<void(uint8_t*)> callback;
00190 } ss_data_req;
00191 
00192 
00193 /**
00194  * @brief   SSInterface is Maxim's SmartSensor Interface class
00195  */
00196 class SSInterface
00197 {
00198 public:
00199 
00200     /* PUBLIC FUNCTION DECLARATIONS */
00201     /**
00202     * @brief    SSInterface constructor.
00203     *
00204     * @param[in]    i2cBus - reference to the I2C bus for the SmartSensor
00205     * @param[in]    ss_mfio - name of SmartSensor multi-function IO pin
00206     * @param[in]    ss_reset - name of SmartSensor Reset pin
00207     *
00208     */
00209     SSInterface(I2C &i2cBus, PinName ss_mfio, PinName ss_reset);
00210 
00211     /**
00212     * @brief    SSInterface constructor.
00213     *
00214     * @param[in]    spiBus - reference to the SPI bus for the SmartSensor
00215     * @param[in]    ss_mfio - name of SmartSensor multi-function IO pin
00216     * @param[in]    ss_reset - name of SmartSensor Reset pin
00217     *
00218     */
00219     SSInterface(SPI &spiBus, PinName ss_mfio, PinName ss_reset);
00220 
00221     /**
00222     * @brief    DSInterface destructor.
00223     *
00224     */
00225     ~SSInterface();
00226 
00227     /**
00228     * @brief    Write a command to the SmartSensor and get status response
00229     *
00230     * @param[in]    cmd_bytes - Pointer to the command's family and index bytes
00231     * @param[in]    cmd_idx_len - The number of bytes in the command
00232     * @param[in]    data - Pointer to the command's data bytes
00233     * @param[in]    data_len - The number data bytes
00234     *
00235     * @return SS_STATUS byte
00236     */
00237     SS_STATUS write_cmd(uint8_t *cmd_bytes, int cmd_bytes_len,
00238                         uint8_t *data, int data_len,
00239                         int sleep_ms = SS_DEFAULT_CMD_SLEEP_MS);
00240 
00241 
00242     /**
00243     * @brief    Write a command to the SmartSensor and get status response
00244     *
00245     * @param[in]    tx_buf - Pointer to the command's family, index bytes and data bytes
00246     * @param[in]    tx_len - Total transaction lenght to send
00247     *
00248     * @return SS_STATUS byte
00249     */
00250     SS_STATUS write_cmd(uint8_t *tx_buf, int tx_len,
00251             int sleep_ms = SS_DEFAULT_CMD_SLEEP_MS);
00252 
00253     /**
00254     * @brief    Write a command to the SmartSensor and get status response
00255     *
00256     * @param[in]    cmd_bytes - Pointer to the command's family and index bytes
00257     * @param[in]    cmd_idx_len - The number of bytes in the command
00258     * @param[in]    data - Pointer to the command's data bytes
00259     * @param[in]    data_len - The number data bytes
00260     * @param[in]    rxbuf - Buffer to fill in with read data (including status byte)
00261     * @param[in]    rxbuf_sz - Size of the rx buffer (to prevent overflow)
00262     *
00263     * @return SS_STATUS byte
00264     */
00265     SS_STATUS read_cmd( uint8_t *cmd_bytes, int cmd_bytes_len,
00266                         uint8_t *data, int data_len,
00267                         uint8_t *rxbuf, int rxbuf_sz,
00268                         int sleep_ms = SS_DEFAULT_CMD_SLEEP_MS);
00269 
00270     /**
00271     * @brief    Get a string representing the SmartSensor firmware version
00272     * @details  If in bootloader mode, returns bootloader version
00273     *
00274     * @return   Pointer to firmware version string
00275     */
00276     const char* get_ss_fw_version();
00277 
00278     /**
00279     * @brief    Get a string representing the SmartSensor platform type
00280     *
00281     * @return   Pointer to platform type string
00282     */
00283     const char* get_ss_platform_name();
00284 
00285     /**
00286      * @brief   Reset the SmartSensor and jump to main application
00287      *
00288      * @return  SS_STATUS code indicating success
00289      */ 
00290     SS_STATUS reset_to_main_app();
00291 
00292     /**
00293      * @brief   Reset the SmartSensor and jump to bootloader
00294      *
00295      * @return  SS_STATUS code indicating success
00296      */ 
00297     SS_STATUS reset_to_bootloader();
00298 
00299     /**
00300      * @brief   Reset the SmartSensor
00301      * @details If the SmartSensor was in bootloader, it will jump back into bootloader
00302      *          If the SmartSensor was in main app, it will jump back into main app
00303      *
00304      * @return  SS_STATUS code indicating success
00305      */ 
00306     SS_STATUS reset();
00307 
00308     /**
00309      * @brief       run the self test commands
00310      * param[in]    idx - the id of the sensor for the self test
00311      * param[in]    result - self-test response
00312      * param[in]    sleep_ms - duration of wait for read command
00313      * @return      SS_STATUS code indicating success
00314      */
00315     SS_STATUS self_test(int idx, uint8_t *result, int sleep_ms = SS_DEFAULT_CMD_SLEEP_MS);
00316 
00317     /**
00318      * @brief   Check if SmartSensor is in bootloader mode
00319      *
00320      * @return  1 if in bootloader mode, 0 if in main app, -1 if comm error
00321      */
00322     int in_bootldr_mode();
00323 
00324 
00325     /**
00326      * @brief   Read register from a device onboard SmartSensor
00327      *
00328      * @param[in] idx - Index of device to read
00329      * @param[in] addr - Register address
00330      * @param[out] val - Register value
00331      *
00332      * @return  SS_SUCCESS on success
00333      */
00334     SS_STATUS get_reg(int idx, uint8_t addr, uint32_t *val);
00335 
00336     /**
00337      * @brief   Set register of a device onboard SmartSensor
00338      *
00339      * @param[in] idx - Index of device to read
00340      * @param[in] addr - Register address
00341      * @param[in] val - Register value
00342      * @param[in] byte_size - Size of IC register in bytes
00343      *
00344      * @return  SS_SUCCESS on success
00345      */
00346     SS_STATUS set_reg(int idx, uint8_t addr, uint32_t val, int byte_size);
00347 
00348     /**
00349      * @brief   Dump registers of a device onboard SmartSensor
00350      *
00351      * @param[in] idx - Index of device
00352      * @param[in] reg_vals - Array of addr_val_pairs
00353      * @param[in] reg_vals_sz - Number of items reg_vals can hold
00354      * @param[out] num_regs - Number of registers returned by command
00355      *
00356      * @return  SS_SUCCESS on success
00357      */
00358     SS_STATUS dump_reg(int idx, addr_val_pair* reg_vals, int reg_vals_sz, int* num_regs);
00359 
00360 
00361     /**
00362      * @brief   Enable a device on the SmartSensor
00363      *
00364      * @param[in] idx - Index of device
00365      * @param[in] mode - Mode to set the device to
00366      * @param[in] data_req - Data request
00367      *
00368      * @return  SS_SUCCESS on success
00369      */
00370     SS_STATUS enable_sensor(int idx, int mode, ss_data_req* data_req);
00371 
00372     /**
00373      * @brief   Disable a device on the SmartSensor
00374      *
00375      * @param[in] idx - Index of device
00376      *
00377      * @return  SS_SUCCESS on success
00378      */
00379     SS_STATUS disable_sensor(int idx);
00380 
00381     /**
00382      * @brief   Enable an algorithm on the SmartSensor
00383      *
00384      * @param[in] idx - Index of device
00385      * @param[in] mode - Mode to set the device to
00386      * @param[in] data_req - Data request
00387      *
00388      * @return  SS_SUCCESS on success
00389      */
00390     SS_STATUS enable_algo(int idx, int mode, ss_data_req* data_req);
00391 
00392     /**
00393      * @brief   Disable an algorithm on the SmartSensor
00394      *
00395      * @param[in] idx - Index of device
00396      *
00397      * @return  SS_SUCCESS on success
00398      */
00399     SS_STATUS disable_algo(int idx);
00400 
00401 
00402     /**
00403      * @brief   Set the CommChannel Output Mode options
00404      *
00405      * @param[in] data_type - Set to 0 for only algorithm data
00406      *                          Set to 1 for only raw sensor data
00407      *                          Set to 2 for algo + raw sensor data
00408      *                          Set to 3 for no data
00409      * @param[in] sc_en - Set to true to receive 1 byte sample count from SmartSensor
00410      *
00411      * @return  SS_SUCCESS on success
00412      */
00413     SS_STATUS set_data_type(int data_type, bool sc_en);
00414 
00415     /**
00416      * @brief   Get the CommChannel Output Mode options
00417      *
00418      * @param[out] data_type - 0 for only algorithm data
00419      *                          1 for only raw sensor data
00420      *                          2 for algo + raw sensor data
00421      *                          3 for no data
00422      * @param[in] sc_en - If true, SmartSensor prepends data with 1 byte sample count
00423      *
00424      * @return  SS_SUCCESS on success
00425      */
00426     SS_STATUS get_data_type(int* data_type, bool *sc_en);
00427 
00428     void enable_irq();
00429     void disable_irq();
00430 
00431     void mfio_selftest();
00432     bool reset_mfio_irq();
00433 
00434 private:
00435 
00436     /* PRIVATE VARIABLES */
00437     I2C *m_i2cBus;
00438     SPI *m_spiBus;
00439     DigitalInOut mfio_pin;
00440     DigitalInOut reset_pin;
00441     InterruptIn irq_pin;
00442 
00443     char fw_version[128];
00444     const char* plat_name;
00445 
00446     bool sc_en;
00447     int data_type;
00448 
00449     int sensor_enabled_mode[SS_MAX_SUPPORTED_SENSOR_NUM];
00450     int algo_enabled_mode[SS_MAX_SUPPORTED_ALGO_NUM];
00451     ss_data_req* sensor_data_reqs[SS_MAX_SUPPORTED_SENSOR_NUM];
00452     ss_data_req* algo_data_reqs[SS_MAX_SUPPORTED_ALGO_NUM];
00453 
00454     /* PRIVATE METHODS */
00455     SS_STATUS write_cmd_small(uint8_t *cmd_bytes, int cmd_bytes_len,
00456                             uint8_t *data, int data_len,
00457                             int sleep_ms = SS_DEFAULT_CMD_SLEEP_MS);
00458     SS_STATUS write_cmd_large(uint8_t *cmd_bytes, int cmd_bytes_len,
00459                             uint8_t *data, int data_len,
00460                             int sleep_ms = SS_DEFAULT_CMD_SLEEP_MS);
00461     void cfg_mfio(PinDirection);
00462 
00463     void irq_handler();
00464 
00465     void irq_handler_selftest();
00466     volatile bool mfio_int_happened;
00467 
00468     SS_STATUS read_fifo_data(int num_samples, int sample_size, uint8_t* databuf, int databuf_sz);
00469     SS_STATUS num_avail_samples(int* num_samples);
00470     void fifo_sample_size(int data_type, int* sample_size);
00471 };
00472 
00473 
00474 #endif