Other than a few device-specific details, most of the MaxThermo action will involve the following methods. There are general (setup/temperature), logging-related and log/sample manipulation and device-specific methods.
General
These are the methods you’re most likely to need when interacting with any of the MaxThermo-supported devices (Max31855, Max6675, DS7505).
In essence the process involves:
// 1) device construction
MaxThermo::DEVICE_TYPE myDevice(...);
// 2) setup
void setup() {
// ...
myDevice.begin();
}
// 3) usage
void loop() {
if ( myDevice.update() == MaxThermo::Status:OK )
{
print_temp(myDevice.temp());
}
}
We’ll go over details for each below.
Constructors
The constructors are device specific, see the details for whichever device you are using: Max31855, Max6675 or DS7505.
begin([param])
After your device object has been instantiated, and prior to making any of the calls below, you must call
begin() so we can ensure everything is setup. This is similar to the Serial.begin() call for the Arduino Serial and would, likewise, be called once in your setup() function. The optional parameter is device-specific, see the details for your device for more info.
update()
MaxThermo maintains a cache of the last reading, from which the results of the various getter methods are returned. Calling update()
communicates with the thermocouple/thermostat and performs an actual read of the device.
Returns a MaxThermo::Status::Result, normally MaxThermo::Status::OK if all went well but can be MaxThermo::Status::LogFull when logging or one of the error messages (OpenCircuit, etc).
status()
The status returned during the last update(), of type MaxThermo::Status::Result.
isOK() isFault() circuitOpen() circuitShort()
Convenience methods for analyzing the status(), returns a boolean as appropriate (e.g. circuitShort() returns true if the status was ShortToGround or ShortToVcc).
temp()/thermoTemp()
Returns the real temperature measured by the device as a floating point number.
tempAsInt()/thermoTempAsInt()
Returns the integer value of the temperature measured by the device.
tempIsNegative()/thermoTempIsNegative()
Returns true if the measured temperature is below 0 degrees Celsius.
internalTemp() internalTempAsInt() internalTempIsNegative()
These methods relate to device-internal measurements, where applicable (e.g. the Max31855). They behave as the three
thermoTemp*() methods above, and will simply return 0/false for devices that don’t have support for sampling the internal temperature.
quickReads()/setQuickReads(bool)
Some devices can be used to provide two levels of information (like the Max31855, for which you can choose to query only the first two bytes of thermocouple data, or instead get a full four bytes that includes internal temp and specifics on any faults encountered). In these cases, have the “quick reads” set to true will reduce the amount of time spent communicating with the device at the cost of a reduced level of information being available.
Logging
MaxThermo has a few built-in features that help make collection and manipulation of multiple samples (“logs”) easier and more memory efficient. See the TempLogger example for sample of working code.
To use the logging facilities, you need to construct a sample container of the appropriate type (a MaxThermo::DEVICE_TYPE::SampleLog) and this array must be global, or at least stay memory-resident during use. For instance:
#define num_samples 100 MaxThermo::Max31855::SampleLog my_samples[num_samples];// …
startLoggingTo(sample_container, container_size)
When you are are ready to begin filling the container with samples (measurements from the device) call the
startLoggingTo() method, informing it of which container to use and the available space (number of samples to collect). For instance: myDevice.startLoggingTo(my_samples, num_samples);
From this point on, each call to update() will add a new sample to the log until it is filled or you manually stop the collection process. Once update()/status() begin returning MaxThermo::Status::LogFull, you must call stopLogging() to inform the library that you know the container has been filled, and take appropriate action.
pauseLogging()
Once you’ve called startLogging(), a call to pauseLogging() will cease adding update()s to the sample container but retain the current logging state.
resumeLogging()
A call to resumeLogging() will re-enable additions to the sample container after a pauseLogging().
stopLogging()
You may call stopLogging() at any time after startLogging(), and it will return the number of samples collected so far. When logging, calls to update will eventually return MaxThermo::Status::LogFull. At that point, you must call stopLogging() to tell the library that you know the log is full and do whatever you need with the data in the sample container.
Sample Manipulation
Once you have a log of samples–a filled MaxThermo::DEVICE_TYPE::SampleLog array–you probably want to manipulate the data in some way. There are two built-in methods available to do so.
getSample(sample_container, index)
Call getSample() by passing it the SampleLog array and the sample index of interest (must be small than the actual SampleLog array size). The method will return a MaxThermo::DEVICE_TYPE::Sample object. This Sample object is device-specific, but provides an interface of its own to access the thermo() and internal() data–see the TempLogger example and/or the library source if you’re into that sort of thing.
logSummary(sample_container, container_size)
Using logSummary() by passing in the SampleLog array and it’s size will return a MaxThermo::ThermocoupleDevice::LogSummary structure with the following attributes:
entries_total // the number of samples entries_valid // the number of valid readings faults // the number of faulty readings maximumTemperature // the max temp encountered (floating point) minimumTemperature // the min temp encountered (floating point) averageTemperature // the average temp in the samples (floating point)
The TempLogger example uses this to print out info on the generated log.