|
HaptiCap
0.1
Directional feedback built into a hat
|
|
HaptiCap
0.1
Directional feedback built into a hat
|
Public Member Functions | |
| HaptiCapMagSettings (uint32_t base_location=0x00) | |
| Class for access to the HaptiCap Magnetometer settings. More... | |
| float | getDeclination (void) |
| float | getInclination (void) |
| float | getSampleRate (void) |
| uint16_t | getPulseWidth (void) |
| uint8_t | getNMotors (void) |
| float | getPhaseOffset (void) |
| bool | getUseCalibration (void) |
| uint8_t | getGain (void) |
| uint8_t | getAveraging (void) |
| int8_t | getPinLoc (uint8_t motor) |
| uint8_t | getMotorCal (uint8_t motor) |
| uint8_t | setDeclination (float declination) |
| uint8_t | setInclination (float inclination) |
| uint8_t | setSampleRate (float sample_rate) |
| uint8_t | setPulseWidth (uint16_t pulse_width) |
| uint8_t | setNMotors (uint8_t n_motors) |
| uint8_t | setPhaseOffset (float phi) |
| uint8_t | setUseCalibration (bool use) |
| uint8_t | setGain (uint8_t gain) |
| uint8_t | setAveraging (uint8_t avg_rate) |
| uint8_t | setPinLoc (uint8_t motor, int8_t pin_loc) |
| uint8_t | setMotorCal (uint8_t motor, uint8_t motor_cal) |
| uint8_t | setMotorCal (uint8_t motor, float motor_cal) |
| uint8_t | writeAll (void) |
| uint8_t | readAll (void) |
| uint8_t | get_err_code (void) |
| uint8_t | calculateChecksum (uint8_t settings_version=HC_SETTINGS_VERSION) |
| uint8_t | readChecksum (void) |
Definition at line 146 of file HaptiCapMagSettings.h.
| HaptiCapMagSettings::HaptiCapMagSettings | ( | uint32_t | base_location = 0x00 | ) |
Class for access to the HaptiCap Magnetometer settings.
Constructor for the HaptiCapMagSettings class
| [in] | base_location | The location in EEPROM memory to read and write the settings. The settings takes 72 bytes, so ensure that the the base location is no less than 72 bytes from the end of the memory location. |
Definition at line 17 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::calculateChecksum | ( | uint8_t | settings_version = HC_SETTINGS_VERSION | ) |
Calculates an 8-bit checksum of all the settings
In order to validate that the settings stored in the EEPROM were validly set by this library or a previous incarnation, a checksum of all the settings is calculated using the crc16() function. The value stored at HC_CHECKSUM_ADDR should match the output of this function after a call to readAll() but before any calls to setter functions. When checking the validity of the stored settings, pass the output of readSettingsVersion() to this function, to ensure backwards compatibility.
| [in] | settings_version | The version of the settings file used when storing the data. This parameter is set by default to the current settings version, but should be used when validating settings as read to ensure backward compatibility. |
Definition at line 873 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::get_err_code | ( | void | ) |
Get the error code from the current settings object.
Definition at line 506 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::getAveraging | ( | void | ) |
Get the averaging rate value fromt he current settings object.
See setAveraging() for more details.
Definition at line 134 of file HaptiCapMagSettings.cpp.
| float HaptiCapMagSettings::getDeclination | ( | void | ) |
Get the declination from the current settings object.
See setDeclination() for more details.
Definition at line 46 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::getGain | ( | void | ) |
Get the gain value from the current settings object.
See setGain() for details.
Definition at line 123 of file HaptiCapMagSettings.cpp.
| float HaptiCapMagSettings::getInclination | ( | void | ) |
Get the inclination from the current settings object.
See setInclination() for more details.
Definition at line 57 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::getMotorCal | ( | uint8_t | motor | ) |
Get the motor calibration for a given motor.
See setMotorCal() for more details.
Definition at line 161 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::getNMotors | ( | void | ) |
Get the number of motors from the current settings object.
See setNMotors() for more details.
Definition at line 90 of file HaptiCapMagSettings.cpp.
| float HaptiCapMagSettings::getPhaseOffset | ( | void | ) |
Get the phase offset from the current settings object.
See setPhaseOffset() for more details.
Definition at line 101 of file HaptiCapMagSettings.cpp.
| int8_t HaptiCapMagSettings::getPinLoc | ( | uint8_t | motor | ) |
Get the pin location for a given motor.
See setPinLoc() for more details.
Definition at line 145 of file HaptiCapMagSettings.cpp.
| uint16_t HaptiCapMagSettings::getPulseWidth | ( | void | ) |
Get the pulse width from the current settings object.
See setPulseWidth() for more details.
Definition at line 79 of file HaptiCapMagSettings.cpp.
| float HaptiCapMagSettings::getSampleRate | ( | void | ) |
Get the sample rate from the current settings object.
See setSampleRate() for more details.
Definition at line 68 of file HaptiCapMagSettings.cpp.
| bool HaptiCapMagSettings::getUseCalibration | ( | void | ) |
Get the useCalibration flag from the current settings object.
See setUseCalibration() for more details.
useCalibration flag.Definition at line 112 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::readAll | ( | void | ) |
Read the values from the EEPROM memory into this settings object
EC_INVALID_CHECKSUM on invalid checksum.Definition at line 475 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::readChecksum | ( | void | ) |
Read the checksum from the EEPROM memory.
The checksum is used to ensure that base_addr points to a legitimate, non-corrupted EEPROM file. This allows us to validate that this program (or an earlier version of it) wrote the settings we are now reading. The checksum is not any sort of cryptographically strong hash, and only uses a single byte, making deliberate collisions trivially simple to calculate, but this should protect against accidentally overwriting the reserved section of memory, or non-initialized settings files.
Definition at line 712 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setAveraging | ( | uint8_t | avg_rate | ) |
Set the averaging rate for the HMC5883L magnetometer.
| [in] | averaging_rate | The number of averages per measurement from the magnetometer will be set to 1<<averaging_rate. If using the provided HMC5883L library, aliases are defined for the valid values:
|
EC_INVALID_AVG_SETTING.Definition at line 343 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setDeclination | ( | float | declination | ) |
Set the declination offset for the current settings object, in degrees
Declination is the offset angle between magnetic north and the direction which you'd like to indicate - generally true north. This depends on your geographic location. You can use the NOAA declination calculator to calculate the declination in heading from magnetic north to true north. Use negative numbers for east and positive numbers for west. Range is +/- 180.0, numbers outside that range will wrap around.
If you'd like to indicate some other direction, you can then calculate the declination of your chosen waypoint vs. true north at your location. Keep in mind that the distance between you and your waypoint can have a profound effect on the declination error introduced by moving around; as such, this setting is not useful for indicating nearby waypoints.
| [in] | decl | The declination in degrees, which wraps at ±180. |
Definition at line 177 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setGain | ( | uint8_t | gain | ) |
Set the gain value for the HMC5883L magnetometer.
| [in] | gain | The gain value. If using the provided HMC5883L library, aliases are defined for the valid values: |
| Alias | gain_value | Gain (LSB/G) | Range (G) | Resolution (mG / LSB) |
|---|---|---|---|---|
HMC_GAIN088 | 0 | 1370 | ±0.88 | 0.73 |
HMC_GAIN130 | 1 | 1090 | ±1.30 | 0.92 |
HMC_GAIN190 | 2 | 820 | ±1.90 | 1.22 |
HMC_GAIN250 | 3 | 660 | ±2.50 | 1.52 |
HMC_GAIN400 | 4 | 440 | ±4.00 | 2.27 |
HMC_GAIN470 | 5 | 390 | ±4.70 | 2.56 |
HMC_GAIN560 | 6 | 330 | ±5.60 | 3.03 |
HMC_GAIN810 | 7 | 230 | ±8.10 | 4.35 |
Future versions may include an auto-gain setting, gain is determined adaptively.
EC_INVALID_GAIN_SETTING if an invalid gain value is specified.Definition at line 312 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setInclination | ( | float | inclination | ) |
Set the inclination offset for the current settings object, in degrees
Inclination is the offset angle between the x-y plane and the z-axis of the magnetic field vector. For simple directional headings, you generally don't need to take the inclination into account. It is included however in case you want to indicate a three-dimensional magnetic field vector.
| [in] | incl | The inclination in degrees, which wraps at ±180. |
Definition at line 201 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setMotorCal | ( | uint8_t | motor, |
| uint8_t | motor_cal | ||
| ) |
Set the motor calibration for motor motor in the current settings object.
Based on the position and strength of each motor, the perceived intensity of the motors may differ (e.g. motors located close to the ear tend to feel stronger than those located in the back of the head). The motorCals array specifies the duty cycle for each motor, which, for a sufficiently short pulseWidth, should be subjectively equivalent to a reduction in the motor intensity.
The duty cycle is expressed in units of 1/255, so a 50% duty cycle is represented as 128, etc. A convenience method for specifying duty cycles as floats is provided as setMotorCal(uint8_t, float).
| [in] | motor | The motor whose calibration is to be set. This value must not exceed HC_MAX_NMOTORS. |
| [in] | motor_cal | The motor calibration duty cycle, specified as a number between 0 and 255. The duty cycle will be interpreted as motorCal/255.0. |
EC_INVALID_MOTOR if an invalid motor is specified.Definition at line 395 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setMotorCal | ( | uint8_t | motor, |
| float | motor_cal | ||
| ) |
Set the motor calibration for motor motor in the current settings object from duty cycle.
Alias for setMotorCal(uint8_t, uint8_t) which takes a float as input.
| [in] | motor_cal | A float in the range [0.0, 1.0] representing the duty cycle. This will be represented as a fraction of 255, rounded to the nearest integer (as opposed to the floor, which is default behavior when casting from float to int). |
EC_INVALID_DUTY_CYCLE if an invalid motor_cal is specified. Errors also can arise from an internal call to setMotorCal(uint8_t, uint8_t).Definition at line 425 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setNMotors | ( | uint8_t | n_motors | ) |
Sets the number of motors for the current settings object.
If the number of motors built into the HaptiCap is changed, update this setting.
| [in] | n_motors | The number of motors in the HaptiCap. Minimum is 1, maximum is HC_MAX_NMOTORS. |
EC_INVALID_N_MOTORS if an invalid number of motors is specified.Definition at line 259 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setPhaseOffset | ( | float | phi | ) |
Sets the phase offset for the current settings object, in degrees. Wraps at ±180.
The default assumption is that the motors are evenly arrayed around the band of the cap, with the 0 motor located at 0°. This offset can be used to adjust the assumed location of the 0 motor.
| [in] | phi | The phase offset of the 0 motor. Wraps at ±180 |
Definition at line 279 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setPinLoc | ( | uint8_t | motor, |
| int8_t | pin_loc | ||
| ) |
Set the pin location for the specified motor.
Each motor is actuated by a specific pin (either the output pin of a multiplexer or one of the digital IO pins of the microcontroller). This setting defines the mapping between motor number and pin location.
| [in] | motor | The motor whose pin location you are specifying. Must be less than HC_MAX_NMOTORS. |
| [in] | pin_loc | The pin location which actuates the specified motor. Specify a negative value if the motor is not used. Invalid pin locations are stored as -1. |
EC_INVALID_MOTOR if motor >= HC_MAX_NMOTORS.Definition at line 367 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setPulseWidth | ( | uint16_t | pulse_width | ) |
Set the pulse width for the current settings object, in milliseconds
Motor calibrations are expressed as fractional duty cycles - the vibrator motors are pulsed on and off over the period pulse_width. For sufficiently short pulse widths, this is experienced as continuous vibration with the strength scaled by the duty cycle. For longer pulse widths, it is experienced as intermittent vibration.
| [in] | pulse_width | The pulse width, in milliseconds |
Definition at line 241 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setSampleRate | ( | float | sample_rate | ) |
Set the sample rate for the current settings object, in Hz.
In continuous read mode, the HMC5883L takes samples at one of the 7 set data output rates, ranging from 0.75 Hz to 75 Hz. In single shot mode, the data output rate is limited by the rate at which data are polled, and can be up to 160 Hz. This controls the rate at which the data are requested.
| [in] | sample_rate | The sample rate at which the magnetometer will be polled, in Hz. Limited to between 0.75 and 160. |
HC_EC_BAD_SAMPLERATE if an invalid sample rate is specified.Definition at line 218 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::setUseCalibration | ( | bool | use | ) |
Set the useCalibration flag for the current settings object.
The HMC5883L magnetometer has a self-test procedure wherein known fields are applied along all three axes for calibration, using built-in coils. These can be used to calibrate the response along the three axes, potentially providing a more accurate heading value. The primary danger in using the calibration is that, because the single calibration value is used for all measurements, errors in calibration may result in systematic errors.
| [in] | use | The new value for the useCalibration flag. |
Definition at line 294 of file HaptiCapMagSettings.cpp.
| uint8_t HaptiCapMagSettings::writeAll | ( | void | ) |
Write the values from the settings object to the EEPROM memory
| [in] | motorCal | A float in the range [0.0, 1.0] representing the duty cycle. This will be represented as a fraction of 255, rounded to the nearest integer (as opposed to the floor, which is default behavior when casting from float to int). |
Definition at line 443 of file HaptiCapMagSettings.cpp.
1.8.8