ADDING_SENSORS.md

OpenLog Artemis : How To Add A New Sensor

These are abbreviated instructions on how to add a new sensor to the OLA firmware. It's more of an aide-memoire really... Sorry about that.

Caveat: this is currently how a new sensor is added, for version v1.n of the OLA firmware using v1.2.n of the Apollo3 boards (the OLA code is compiled using the SparkFun RedBoard Artemis ATP (All The Pins) board). This will change, dramatically, when we upgrade to v2 of Apollo3 and integrate BLE support.

Use The Release Candidate Branch

First up, please target any commits at the release_candidate branch, so they can be tested before being merged into the main branch.

• https://github.com/sparkfun/OpenLog_Artemis/tree/release_candidate

OpenLog_Artemis.ino

• Add the new sensor to the comments at the start of the file

• #include the library .h file remembering to include the library manager helper link

Sensors.ino

gatherDeviceValues

• This is where the sensor readings are actually read. Add a case for the new sensor

printHelperText

• Add helper text for the sensor readings

autoDetect.ino

addDevice

• This code is called to add the discovered device to the linked list of active devices. Add a case for the new sensor. The class name comes from the library. The config struct is defined in settings.h.

beginQwiicDevices

• This is the code that is called to start (begin) the device. Add a case for the new sensor. Update qwiicPowerOnDelayMillis if this device needs extra time to get its act together on power-up.

configureDevice

• If the sensor needs to be configured before use, that gets done here. Add a case for the new sensor, even if it doesn't need to be configured.

getConfigFunctionPtr

• Add a pointer to the sensor menu function (defined in menuAttachedDevices.ino)

swap

• Add the device's I2C address(es) here - just for reference (we don't use these #defines any longer)

testDevice

• This is the code used to detect the sensor. Add a case for the new sensor. Provide some indication of how robust the detection is. Confidence would be high if the .begin writes and reads unique data to/from the sensor. Confidence is low if .begin only uses the standard isConnected I2C address test.

getDeviceName

• This is where the sensor name is defined as text. Add a case for the new sensor. Keep it brief and follow the same format as the other sensors: usually TYPE (PRESSURE, TEMPERATURE etc.) followed by the abbreviated manufacturer's part number

menuAttachedDevices.ino

menuAttachedDevices

• This is the code which lists all the attached devices as a menu. Add a case for the new sensor

menuConfigure_

• Add a new menuConfigure_ for the new sensor
• Boolean settings are simple to toggle. Make them exclusive if you need to
• int64_t values are requested using getNumber (defined in support.ino)
• double values are requested using getDouble (defined in support.ino)

nvm.ino

recordDeviceSettingsToFile

• This function gets called to write the device settings to file. Add a case for the new sensor. Include all of the sensor settings.

parseDeviceLine

• This function gets called when the device settings are read back from file. Add a case for the new sensor

settings.h

enum

• Add the device to the enumerated sensors. Insert the new one above DEVICE_TOTAL_DEVICES

settings struct

• Add a settings struct for the new sensor. Include both log and powerOnDelayMillis

README.md

• Add the new sensor to the list in README.md. Include a link to the product page
• Update the OLA product page on Sparkle - add the new sensor to the list

CHANGELOG.md

• Update CHANGELOG.md. Start a new version if you need to. Add the new sensor to the change notes

SENSOR_UNITS.md

• Update SENSOR_UNITS.md. Add the new sensor to the appropriate section at the start of the document. Add a unit table for the sensor at the end of the document.