First Commit as a new library
Dependents: Host_Software_MAX32664GWEB_HR_wrist Host_Software_MAX32664GWEC_SpO2_HR Host_Software_MAX32664GWEB_HR_EXTENDED Host_Software_MAX32664GWEC_SpO2_HR-_EXTE ... more
Diff: bmi160.h
- Revision:
- 21:f7216b5dc6c0
- Parent:
- 20:a521606048bb
diff -r a521606048bb -r f7216b5dc6c0 bmi160.h --- a/bmi160.h Fri May 04 13:35:59 2018 +0300 +++ b/bmi160.h Wed Dec 19 14:54:05 2018 +0300 @@ -46,7 +46,7 @@ battery driven devices. It is available in a compact 14-pin 2.5 x 3.0 x 0.8 mm³ LGA package." -This class is an abstract base class and can not be instaniated, use BMI160_I2C +This class is an abstract base class and can not be instaniated, use BMI160_I2C or BMI160_SPI. */ class BMI160 @@ -55,7 +55,7 @@ ///Return value on success. static const uint8_t RTN_NO_ERROR = 0; - + ///Sensor types enum Sensors { @@ -63,7 +63,7 @@ GYRO, ///<Angular rate sensor ACC ///<g sensor }; - + ///Sensor Axis enum SensorAxis { @@ -71,21 +71,24 @@ Y_AXIS, Z_AXIS }; - + ///Structure for axis data struct AxisData { int16_t raw; ///<Axis raw data - float scaled; ///<Axis scaled data + float scaled; ///<Axis scaled data }; - + ///Structure for sensor time data struct SensorTime { uint32_t raw; ///<raw SensorTime float seconds; ///<SensorTime as seconds }; - + + ///Period of internal counter + static const float SENSOR_TIME_LSB = 39e-6; + ///Structure for holding sensor data struct SensorData { @@ -93,12 +96,12 @@ AxisData yAxis; ///<Sensor Y axis data AxisData zAxis; ///<Sensor Z axis data }; - - + + ///BMI160 registers enum Registers { - CHIP_ID = 0x00, ///<Chip Identification. + CHIP_ID = 0x00, ///<Chip Identification. ERR_REG = 0x02, ///<Reports sensor error flags. Flags reset when read. PMU_STATUS, ///<Reports current power mode for sensors. DATA_0, ///<MAG_X axis bits7:0 @@ -139,10 +142,10 @@ GYR_CONF, ///<Set ODR, bandwidth, and read mode of gyroscope GYR_RANGE, ///<Sets gyroscope angular rate measurement range MAG_CONF, ///<Sets ODR of magnetometer interface - FIFO_DOWNS, ///<Sets down sampling ratios of accel and gyro data + FIFO_DOWNS, ///<Sets down sampling ratios of accel and gyro data ///<for FIFO FIFO_CONFIG_0, ///<Sets FIFO Watermark - FIFO_CONFIG_1, ///<Sets which sensor data is available in FIFO, + FIFO_CONFIG_1, ///<Sets which sensor data is available in FIFO, ///<Header/Headerless mode, Ext Int tagging, Sensortime MAG_IF_0 = 0x4B, ///<Magnetometer 7-bit I2C address, bits7:1 MAG_IF_1, ///<Magnetometer interface configuration @@ -153,40 +156,40 @@ INT_EN_1, ///<Interrupt enable bits INT_EN_2, ///<Interrupt enable bits INT_OUT_CTRL, ///<Contains the behavioral configuration of INT pins - INT_LATCH, ///<Contains the interrupt rest bit and the interrupt + INT_LATCH, ///<Contains the interrupt rest bit and the interrupt ///<mode selection - INT_MAP_0, ///<Controls which interrupt signals are mapped to the + INT_MAP_0, ///<Controls which interrupt signals are mapped to the ///<INT1 and INT2 pins - INT_MAP_1, ///<Controls which interrupt signals are mapped to the + INT_MAP_1, ///<Controls which interrupt signals are mapped to the ///<INT1 and INT2 pins - INT_MAP_2, ///<Controls which interrupt signals are mapped to the + INT_MAP_2, ///<Controls which interrupt signals are mapped to the ///<INT1 and INT2 pins - INT_DATA_0, ///<Contains the data source definition for the two + INT_DATA_0, ///<Contains the data source definition for the two ///<interrupt groups - INT_DATA_1, ///<Contains the data source definition for the two + INT_DATA_1, ///<Contains the data source definition for the two ///<interrupt groups INT_LOWHIGH_0, ///<Contains the configuration for the low g interrupt INT_LOWHIGH_1, ///<Contains the configuration for the low g interrupt INT_LOWHIGH_2, ///<Contains the configuration for the low g interrupt INT_LOWHIGH_3, ///<Contains the configuration for the low g interrupt INT_LOWHIGH_4, ///<Contains the configuration for the low g interrupt - INT_MOTION_0, ///<Contains the configuration for the any motion and + INT_MOTION_0, ///<Contains the configuration for the any motion and ///<no motion interrupts - INT_MOTION_1, ///<Contains the configuration for the any motion and + INT_MOTION_1, ///<Contains the configuration for the any motion and ///<no motion interrupts - INT_MOTION_2, ///<Contains the configuration for the any motion and + INT_MOTION_2, ///<Contains the configuration for the any motion and ///<no motion interrupts - INT_MOTION_3, ///<Contains the configuration for the any motion and + INT_MOTION_3, ///<Contains the configuration for the any motion and ///<no motion interrupts INT_TAP_0, ///<Contains the configuration for the tap interrupts INT_TAP_1, ///<Contains the configuration for the tap interrupts - INT_ORIENT_0, ///<Contains the configuration for the oeientation + INT_ORIENT_0, ///<Contains the configuration for the oeientation ///<interrupt - INT_ORIENT_1, ///<Contains the configuration for the oeientation + INT_ORIENT_1, ///<Contains the configuration for the oeientation ///<interrupt INT_FLAT_0, ///<Contains the configuration for the flat interrupt INT_FLAT_1, ///<Contains the configuration for the flat interrupt - FOC_CONF, ///<Contains configuration for the fast offset + FOC_CONF, ///<Contains configuration for the fast offset ///<compensation for the accelerometer and gyroscope CONF, ///<Configuration of sensor, nvm_prog_en bit IF_CONF, ///<Contains settings for the digital interface @@ -204,15 +207,15 @@ STEP_CNT_1, ///<Step counter bits 7:0 STEP_CONF_0, ///<Contains configuration of the step detector STEP_CONF_1, ///<Contains configuration of the step detector - CMD = 0x7E ///<Command register triggers operations like + CMD = 0x7E ///<Command register triggers operations like ///<softreset, NVM programming, etc. }; - - + + ///@name ERR_REG(0x02) ///Error register data ///@{ - + static const uint8_t FATAL_ERR_MASK = 0x01; static const uint8_t FATAL_ERR_POS = 0x00; static const uint8_t ERR_CODE_MASK = 0x1E; @@ -223,26 +226,26 @@ static const uint8_t DROP_CMD_ERR_POS = 0x06; static const uint8_t MAG_DRDY_ERR_MASK = 0x80; static const uint8_t MAG_DRDY_ERR_POS = 0x08; - + ///Enumerated error codes enum ErrorCodes { NO_ERROR = 0, ///<No Error - ERROR_1, ///<Listed as error + ERROR_1, ///<Listed as error ERROR_2, ///<Listed as error - LPM_INT_PFD, ///<Low-power mode and interrupt uses pre-filtered + LPM_INT_PFD, ///<Low-power mode and interrupt uses pre-filtered ///<data - ODR_MISMATCH = 0x06, ///<ODRs of enabled sensors in headerless mode do + ODR_MISMATCH = 0x06, ///<ODRs of enabled sensors in headerless mode do ///<not match PFD_USED_LPM ///<Pre-filtered data are used in low power mode }; ///@} - - - ///@name ACC_CONF(0x40) and ACC_RANGE(0x41) + + + ///@name ACC_CONF(0x40) and ACC_RANGE(0x41) ///Data for configuring accelerometer ///@{ - + static const uint8_t ACC_ODR_MASK = 0x0F; static const uint8_t ACC_ODR_POS = 0x00; static const uint8_t ACC_BWP_MASK = 0x70; @@ -251,7 +254,7 @@ static const uint8_t ACC_US_POS = 0x07; static const uint8_t ACC_RANGE_MASK = 0x0F; static const uint8_t ACC_RANGE_POS = 0x00; - + ///Accelerometer output data rates enum AccOutputDataRate { @@ -268,7 +271,7 @@ ACC_ODR_11, ///< 800Hz ACC_ODR_12 ///< 1600Hz }; - + ///Accelerometer bandwidth parameters enum AccBandWidthParam { @@ -281,14 +284,14 @@ ACC_BWP_6, ///< Average 64 cycles ACC_BWP_7 ///< Average 128 cycles }; - + ///Accelerometer undersampling enum AccUnderSampling { ACC_US_OFF = 0, ACC_US_ON }; - + ///Accelerometer ranges enum AccRange { @@ -297,7 +300,12 @@ SENS_8G = 0x08, ///<Accelerometer range +-8G SENS_16G = 0x0C ///<Accelerometer range +-16G }; - + + static const float SENS_2G_LSB_PER_G = 16384.0F; + static const float SENS_4G_LSB_PER_G = 8192.0F; + static const float SENS_8G_LSB_PER_G = 4096.0F; + static const float SENS_16G_LSB_PER_G = 2048.0F; + ///Accelerometer configuration data structure struct AccConfig { @@ -306,27 +314,27 @@ AccBandWidthParam bwp; ///<Accelerometer bandwidth param AccOutputDataRate odr; ///<Accelerometr output data rate }; - + ///Accelerometer default configuration static const AccConfig DEFAULT_ACC_CONFIG; ///@} - - - ///@name GYR_CONF(0x42) and GYR_RANGE(0x43) + + + ///@name GYR_CONF(0x42) and GYR_RANGE(0x43) ///Data for configuring gyroscope ///@{ - + static const uint8_t GYRO_ODR_MASK = 0x0F; static const uint8_t GYRO_ODR_POS = 0x00; static const uint8_t GYRO_BWP_MASK = 0x30; static const uint8_t GYRO_BWP_POS = 0x04; static const uint8_t GYRO_RANGE_MASK = 0x07; static const uint8_t GYRO_RANGE_POS = 0x00; - + ///Gyroscope output data rates enum GyroOutputDataRate { - GYRO_ODR_6 = 0x06, ///<25Hz + GYRO_ODR_6 = 0x06, ///<25Hz GYRO_ODR_7 = 0x07, ///<50Hz GYRO_ODR_8 = 0x08, ///<100Hz GYRO_ODR_9 = 0x09, ///<200Hz @@ -335,7 +343,7 @@ GYRO_ODR_12 = 0x0C, ///<1600Hz GYRO_ODR_13 = 0x0D ///<3200Hz }; - + ///Gyroscope bandwidth paramaters enum GyroBandWidthParam { @@ -343,7 +351,7 @@ GYRO_BWP_1, ///<OSR2 Over Sampling Rate of 2 GYRO_BWP_2 ///<Normal Mode, Equidistant Sampling }; - + ///Gyroscope ranges enum GyroRange { @@ -351,22 +359,28 @@ DPS_1000, ///<+-1000dps, 32.8LSB/dps DPS_500, ///<+-500dps, 65.6LSB/dps DPS_250, ///<+-250dps, 131.2LSB/dps - DPS_125 ///<+-125dps, 262.4LSB/dps, + DPS_125 ///<+-125dps, 262.4LSB/dps, }; - - ///Gyroscope configuration data structure + + static const float SENS_2000_DPS_LSB_PER_DPS = 16.4F; + static const float SENS_1000_DPS_LSB_PER_DPS = 32.8F; + static const float SENS_500_DPS_LSB_PER_DPS = 65.6F; + static const float SENS_250_DPS_LSB_PER_DPS = 131.2F; + static const float SENS_125_DPS_LSB_PER_DPS = 262.4F; + + ///Gyroscope configuration data structure struct GyroConfig { GyroRange range; ///<Gyroscope range GyroBandWidthParam bwp; ///<Gyroscope bandwidth param GyroOutputDataRate odr; ///<Gyroscope output data rate }; - + ///Gyroscope default configuration static const GyroConfig DEFAULT_GYRO_CONFIG; ///@} - - + + ///Enumerated power modes enum PowerModes { @@ -375,36 +389,36 @@ LOW_POWER, ///<Acc duty-cycling between suspend and normal FAST_START_UP ///<Gyro start up delay time to normal mode <= 10 ms }; - - + + ///Enumerated commands used with CMD register enum Commands { - START_FOC = 0x03, ///<Starts Fast Offset Calibrartion + START_FOC = 0x03, ///<Starts Fast Offset Calibrartion ACC_SET_PMU_MODE = 0x10, ///<Sets acc power mode GYR_SET_PMU_MODE = 0x14, ///<Sets gyro power mode MAG_SET_PMU_MODE = 0x18, ///<Sets mag power mode PROG_NVM = 0xA0, ///<Writes NVM backed registers into NVM FIFO_FLUSH = 0xB0, ///<Clears FIFO - INT_RESET, ///<Clears interrupt engine, INT_STATUS, and + INT_RESET, ///<Clears interrupt engine, INT_STATUS, and ///<the interrupt pin STEP_CNT_CLR, ///<Triggers reset of the step counter SOFT_RESET = 0xB6 ///<Triggers a reset including a reboot. }; - - + + ///@brief BMI160 Destructor.\n /// ///On Entry: - ///@param[in] none + ///@param[in] none /// ///On Exit: ///@param[out] none /// ///@returns none virtual ~BMI160(){ } - - + + ///@brief Reads a single register.\n /// ///On Entry: @@ -415,8 +429,8 @@ /// ///@returns 0 on success, non 0 on failure virtual int32_t readRegister(Registers reg, uint8_t *data) = 0; - - + + ///@brief Writes a single register.\n /// ///On Entry: @@ -427,11 +441,11 @@ /// ///@returns 0 on success, non 0 on failure virtual int32_t writeRegister(Registers reg, const uint8_t data) = 0; - - + + ///@brief Reads a block of registers.\n - ///@detail User must ensure that all registers between 'startReg' and - ///'stopReg' exist and are readable. Function reads up to, including, + ///@detail User must ensure that all registers between 'startReg' and + ///'stopReg' exist and are readable. Function reads up to, including, ///'stopReg'.\n /// ///On Entry: @@ -443,17 +457,17 @@ ///@param[out] data - holds contents of read registers on success /// ///@returns 0 on success, non 0 on failure - virtual int32_t readBlock(Registers startReg, Registers stopReg, + virtual int32_t readBlock(Registers startReg, Registers stopReg, uint8_t *data) = 0; - - + + ///@brief Writes a block of registers.\n - ///@detail User must ensure that all registers between 'startReg' and - ///'stopReg' exist and are writeable. Function writes up to, including, + ///@detail User must ensure that all registers between 'startReg' and + ///'stopReg' exist and are writeable. Function writes up to, including, ///'stopReg'.\n /// ///On Entry: - ///@param[in] startReg - register to start writing at + ///@param[in] startReg - register to start writing at ///@param[in] stopReg - register to stop writing at ///@param[in] data - pointer to data to write to registers /// @@ -461,24 +475,24 @@ ///@param[out] none /// ///@returns 0 on success, non 0 on failure - virtual int32_t writeBlock(Registers startReg, Registers stopReg, + virtual int32_t writeBlock(Registers startReg, Registers stopReg, const uint8_t *data) = 0; - - + + ///@brief Sets sensors power mode through CMD register.\n - ///@details Observe command execution times given in datasheet.\n + ///@details Observe command execution times given in datasheet.\n /// ///On Entry: ///@param[in] sensor - Sensor which power mode we are setting ///@param[in] pwrMode - Desired powermode of the sensor /// ///On Exit: - ///@param[out] + ///@param[out] /// ///@returns 0 on success, non 0 on failure int32_t setSensorPowerMode(Sensors sensor, PowerModes pwrMode); - - + + ///@brief Configure sensor.\n /// ///On Entry: @@ -490,22 +504,22 @@ ///@returns 0 on success, non 0 on failure int32_t setSensorConfig(const AccConfig &config); int32_t setSensorConfig(const GyroConfig &config); - - + + ///@brief Get sensor configuration.\n /// ///On Entry: ///@param[in] config - Sensor configuration data structure /// ///On Exit: - ///@param[out] config - on success, holds sensor's current + ///@param[out] config - on success, holds sensor's current ///configuration /// ///@returns 0 on success, non 0 on failure int32_t getSensorConfig(AccConfig &config); int32_t getSensorConfig(GyroConfig &config); - - + + ///@brief Get sensor axis.\n /// ///On Entry: @@ -519,8 +533,8 @@ ///@returns 0 on success, non 0 on failure int32_t getSensorAxis(SensorAxis axis, AxisData &data, AccRange range); int32_t getSensorAxis(SensorAxis axis, AxisData &data, GyroRange range); - - + + ///@brief Get sensor xyz axis.\n /// ///On Entry: @@ -533,8 +547,8 @@ ///@returns 0 on success, non 0 on failure int32_t getSensorXYZ(SensorData &data, AccRange range); int32_t getSensorXYZ(SensorData &data, GyroRange range); - - + + ///@brief Get sensor xyz axis and sensor time.\n /// ///On Entry: @@ -547,12 +561,12 @@ ///@param[out] sensorTime - Holds sensor time on success /// ///@returns 0 on success, non 0 on failure - int32_t getSensorXYZandSensorTime(SensorData &data, SensorTime &sensorTime, + int32_t getSensorXYZandSensorTime(SensorData &data, SensorTime &sensorTime, AccRange range); - int32_t getSensorXYZandSensorTime(SensorData &data, SensorTime &sensorTime, + int32_t getSensorXYZandSensorTime(SensorData &data, SensorTime &sensorTime, GyroRange range); - - + + ///@brief Get Gyroscope/Accelerometer data and sensor time.\n /// ///On Entry: @@ -568,12 +582,12 @@ ///@param[out] sensorTime - Synchronized sensor time /// ///@returns 0 on success, non 0 on failure - int32_t getGyroAccXYZandSensorTime(SensorData &accData, - SensorData &gyroData, - SensorTime &sensorTime, + int32_t getGyroAccXYZandSensorTime(SensorData &accData, + SensorData &gyroData, + SensorTime &sensorTime, AccRange accRange, GyroRange gyroRange); - - + + ///@brief Get sensor time.\n /// ///On Entry: @@ -584,18 +598,48 @@ /// ///@returns returns 0 on success, non 0 on failure int32_t getSensorTime(SensorTime &sensorTime); - - + + ///@brief Get die temperature.\n /// ///On Entry: - ///@param[in] temp - pointer to float for temperature + ///@param[in] temp - pointer to float for temperature /// ///On Exit: ///@param[out] temp - on success, holds the die temperature /// ///@returns 0 on success, non 0 on failure int32_t getTemperature(float *temp); + + // Initialize BMI160 with default parameters: + // set GYRO: Suspended, Acc Normal Mode, ODR:25 Hz + int32_t BMI160_DefaultInitalize(); + + // + // + int32_t enable_data_ready_interrupt(); + + // + // Set sample rate + // This function can be alled after BMI160_DefaultInitalize + int32_t setSampleRate(int sample_rate); + + /// @brief Soft reset + /// + int32_t reset(); + +private: + bool m_use_irq; + bool bmi160_irq_asserted; + InterruptIn *m_bmi160_irq; + void irq_handler(); + +protected: + BMI160(InterruptIn *int_pin): m_bmi160_irq(int_pin), m_use_irq(true) { + bmi160_irq_asserted = false; + } + + BMI160(): m_use_irq(false) { } }; @@ -610,7 +654,7 @@ static const uint8_t I2C_ADRS_SDO_LO = 0x68; ///BMI160 optional I2C address. static const uint8_t I2C_ADRS_SDO_HI = 0x69; - + ///@brief BMI160_I2C Constructor.\n /// @@ -622,9 +666,21 @@ ///@param[out] none /// ///@returns none - BMI160_I2C(I2C &i2cBus, uint8_t i2cAdrs); - - + BMI160_I2C(I2C *i2cBus, uint8_t i2cAdrs); + + ///@brief BMI160_I2C Constructor.\n + /// + ///On Entry: + ///@param[in] i2cBus - reference to I2C bus for this device + ///@param[in] i2cAdrs - 7-bit I2C address + ///@param[in] int_pin - Interrupt pin + /// + ///On Exit: + ///@param[out] none + /// + ///@returns none + BMI160_I2C(I2C *i2cBus, uint8_t i2cAdrs, InterruptIn *int_pin); + ///@brief Reads a single register.\n /// ///On Entry: @@ -635,8 +691,8 @@ /// ///@returns 0 on success, non 0 on failure virtual int32_t readRegister(Registers reg, uint8_t *data); - - + + ///@brief Writes a single register.\n /// ///On Entry: @@ -647,11 +703,11 @@ /// ///@returns 0 on success, non 0 on failure virtual int32_t writeRegister(Registers reg, const uint8_t data); - - + + ///@brief Reads a block of registers.\n - ///@detail User must ensure that all registers between 'startReg' and - ///'stopReg' exist and are readable. Function reads up to, including, + ///@detail User must ensure that all registers between 'startReg' and + ///'stopReg' exist and are readable. Function reads up to, including, ///'stopReg'.\n /// ///On Entry: @@ -663,17 +719,17 @@ ///@param[out] data - holds contents of read registers on success /// ///@returns 0 on success, non 0 on failure - virtual int32_t readBlock(Registers startReg, Registers stopReg, + virtual int32_t readBlock(Registers startReg, Registers stopReg, uint8_t *data); - - + + ///@brief Writes a block of registers.\n - ///@detail User must ensure that all registers between 'startReg' and - ///'stopReg' exist and are writeable. Function writes up to, including, + ///@detail User must ensure that all registers between 'startReg' and + ///'stopReg' exist and are writeable. Function writes up to, including, ///'stopReg'.\n /// ///On Entry: - ///@param[in] startReg - register to start writing at + ///@param[in] startReg - register to start writing at ///@param[in] stopReg - register to stop writing at ///@param[in] data - pointer to data to write to registers /// @@ -681,12 +737,11 @@ ///@param[out] none /// ///@returns 0 on success, non 0 on failure - virtual int32_t writeBlock(Registers startReg, Registers stopReg, + virtual int32_t writeBlock(Registers startReg, Registers stopReg, const uint8_t *data); - + private: - - I2C &m_i2cBus; + I2C *m_i2cBus; uint8_t m_Wadrs, m_Radrs; }; @@ -708,9 +763,9 @@ ///@param[out] none /// ///@returns none - BMI160_SPI(SPI &spiBus, DigitalOut &cs); - - + BMI160_SPI(SPI *spiBus, DigitalOut &cs); + + ///@brief Reads a single register.\n /// ///On Entry: @@ -721,8 +776,8 @@ /// ///@returns 0 on success, non 0 on failure virtual int32_t readRegister(Registers reg, uint8_t *data); - - + + ///@brief Writes a single register.\n /// ///On Entry: @@ -733,11 +788,11 @@ /// ///@returns 0 on success, non 0 on failure virtual int32_t writeRegister(Registers reg, const uint8_t data); - - + + ///@brief Reads a block of registers.\n - ///@detail User must ensure that all registers between 'startReg' and - ///'stopReg' exist and are readable. Function reads up to, including, + ///@detail User must ensure that all registers between 'startReg' and + ///'stopReg' exist and are readable. Function reads up to, including, ///'stopReg'.\n /// ///On Entry: @@ -749,17 +804,17 @@ ///@param[out] data - holds contents of read registers on success /// ///@returns 0 on success, non 0 on failure - virtual int32_t readBlock(Registers startReg, Registers stopReg, + virtual int32_t readBlock(Registers startReg, Registers stopReg, uint8_t *data); - - + + ///@brief Writes a block of registers.\n - ///@detail User must ensure that all registers between 'startReg' and - ///'stopReg' exist and are writeable. Function writes up to, including, + ///@detail User must ensure that all registers between 'startReg' and + ///'stopReg' exist and are writeable. Function writes up to, including, ///'stopReg'.\n /// ///On Entry: - ///@param[in] startReg - register to start writing at + ///@param[in] startReg - register to start writing at ///@param[in] stopReg - register to stop writing at ///@param[in] data - pointer to data to write to registers /// @@ -767,12 +822,12 @@ ///@param[out] none /// ///@returns 0 on success, non 0 on failure - virtual int32_t writeBlock(Registers startReg, Registers stopReg, + virtual int32_t writeBlock(Registers startReg, Registers stopReg, const uint8_t *data); - + private: - SPI &m_spiBus; + SPI *m_spiBus; DigitalOut m_cs; }; @@ -782,7 +837,7 @@ ///@brief fx documentation template.\n /// ///On Entry: -///@param[in] none +///@param[in] none /// ///On Exit: ///@param[out] none