🔌 Octopus API
The Octopus Arduino Library gives you a variety of methods to use on the octoous-object to modify its behaviour. The overview is found below.
To use this library:
#include <Octopus.h>
The library source files can be found in GitHub: https://github.com/MIT-Senseable-City-Lab/octopus-fabrication/tree/main/firmware
Methods
Public Class Octopus:
initializeSensors(): Sets up all connected sensors with default calibration values
Parameters
None
Returns
1 on success, 0 on failure
Example
if (!Octopus::initializeSensors()) {
Serial.println("Failed to initialize Sensors!");
while (1);
}
setInterval(long interval): sets the interval for data logging
Parameters
long interval
Returns
-
Example
Octopus::setInterval(5000) // sets the interval for data logging to 5 seconds
start(): Begins continuous reading of all sensors
Parameters
None
Returns
1 on success, 0 on failure
Example
if (!Octopus::start()) {
Serial.println("Failed to start data collection!");
while (1);
}
readTemperature(): Returns the current temperature reading
Parameters
None
Returns
Temperature (float) on on success, 0 on failure
Example
Serial.print("Temperature = ");
Serial.print(Octopus::readTemperature());
Serial.println(" °C");
readHumidity(): Returns the current humidity level
Parameters
None
Returns
Humidity (float) on success, 0 on failure
Example
Serial.print("Humidity = ");
Serial.print(Octopus::readHumidity());
Serial.println(" %");
SPS30 Functions
initializeSPS30(): Initializing the SPS30 sensor
Parameters
None
Returns
1 on on success, 0 on failure
Example
// Sensor availability flags
bool sps30Available = false;
sps30Available = Octopus::initializeSPS30();
readSPS30Data(float pm1_0, float pm2_5, float pm4_0, float pm10_0): Function for reading SPS30 data
Parameters
- float pm1_0: variable to save PM1.0 value
- float pm2_5: variable to save PM2.5 value
- float pm4_0: variable to save PM4.0 value
float pm10_0: variable to save PM10 value
Returns
1 on on success, 0 on failure
Example
// Read SPS30 data if available
float pm1_0 = 0, pm2_5 = 0, pm4_0 = 0, pm10_0 = 0;
if (sps30Available) {
if (!Octopus::readSPS30Data(pm1_0, pm2_5, pm4_0, pm10_0)) {
Serial.println("Failed to read SPS30 data");
}
}
stopSPS30(): Stop the SPS30 sensor
Parameters
None
Returns
1 on on success, 0 on failure
Example
if (sps30Available) {
Octopus::stopSPS30();
}
GPS Functions
initializeGPS(): Initialize GPS
Parameters
None
Returns
1 on on success, 0 on failure
Example
// Sensor availability flags
bool gpsAvailable = false;
gpsAvailable = Octopus::initializeGPS();
readGPSData(float latitude, float longitude, float altitude): Read GPS data
Parameters
- float latitude: variable to save latitude
- float longitude: variable to save longitude
- float altitude: variable to save altitude
Returns
1 on on success, 0 on failure
Example
// Read GPS data if available
float latitude = 0, longitude = 0, altitude = 0;
if (gpsAvailable) {
if (!Octopus::readGPSData(latitude, longitude, altitude)) {
Serial.println("Failed to read GPS data");
}
}
getGPSTime(): Get GPS time as a string
Parameters
None
Returns
GPS time as a string on on success, "0.00" on failure
Example
// Get GPS time if available
String gpsTime = "N/A";
if (gpsAvailable) {
gpsTime = Octopus::getGPSTime();
}
Battery and LED control functions
initBatteryMonitoring(): Set LED up for use, ensuring its ready to display battery-related information through color changes
Parameters
None
Returns
-
Example
// If start-button is pressed, monitor battery and initialize SPS30
if (buttonPressTime != 0) {
if (!longPressHandled) {
deviceOn = true;
Serial.println("Device turned on");
initSD(RECORDS_PER_FILE);
initBatteryMonitoring();
if (sps30Available) {
Octopus::initializeSPS30();
}
}
setDotStarColor((uint8_t r, uint8_t g, uint8_t b): Adjusts the RGB LED color based on provided red, green, and blue values
Note that this only changes one of the LEDs as the other one is configured to provide information on battery levels (turn red if battery is low).
Parameters
- uint8_t r: variable to indicate level of RED in the LED, values between 0-255 is valid.
- uint8_t g: variable to indicate level of GREEN in the LED, values between 0-255 is valid.
- uint8_t b: variable to indicate level of BLUE in the LED, values between 0-255 is valid.
Returns
-
Example
void loop() {
setDotStarColor(0, 0, 255); // LED set to BLUE
delay(500);
setDotStarColor(0, 255, 0); // LED set to GREEN
delay(500);
setDotStarColor(255, 0, 0); // LED set to RED
delay(500);
}
calculateBatteryPercentage(float voltage): Returns the current battery level as a percentage
Parameters
float voltage
Returns
float: Current battery presentage calculated
Example
// Battery monitoring and RGB LED control
const int vbatPin = A0;
const int chargeStatePin = 7;
int vbatRaw = analogRead(vbatPin);
float vbatVoltage = vbatRaw * (3.294 / 1023.0) * 1.279;
bool chargeState = digitalRead(chargeStatePin);
bool batteryConnected = vbatVoltage > 2.5;
float batteryPercentage = batteryConnected ? calculateBatteryPercentage(vbatVoltage) : 0.0;
Functions for SD Card Handling
initSD(int recordsPerFile): Init SD card and set records per file
Parameters
- int recordsPerFile: number of records per file stored to SD card
Returns
-
Example
deviceOn = true;
Serial.println("Device turned on");
initSD(RECORDS_PER_FILE);
logToSD(): data logging if you are logging to SD card
Parameters
String
Returns
-
Example
// Log the data (Include placeholders or skip the SPS30 values if not available)
String data = gpsTime + "," + String(latitude, 7) + "," + String(longitude, 7) + "," + temperature + "," + humidity;
if (sps30Available) {
data += "," + String(pm1_0) + "," + String(pm2_5) + "," + String(pm4_0) + "," + String(pm10_0);
} else {
data += ",N/A,N/A,N/A,N/A"; // Placeholder if SPS30 data is unavailable
}
logToSD(data);