Skip to content

rtcfifo module documentation

Jump to bottom Edit New page
Johny Mattsson edited this page Jul 10, 2015 · 2 revisions

###rtcfifo module

#rtcfifo module The rtcfifo module implements a first-in,first-out storage intended for sensor readings. As the name suggests, it is backed by the RTC user memory and as such survives deep sleep cycles. Conceptually it can be thought of as a cyclic array of { timestamp, name, value } tuples. Internally it uses a space-optimized storage format to allow the greatest number of samples to be kept. This comes with several trade-offs, and as such is not a one-solution-fits-all. Notably:

  • Timestamps are stored with second-precision.
  • Sample frequency must be at least once every 8.5 minutes. This is a side-effect of delta-compression being used for the time stamps.
  • Values are limited to 16 bits of precision, but have a separate field for storing an E-n multiplier. This allows for high fidelity even when working with very small values. The effective range is thus 1E-7 to 65535.
  • Sensor names are limited to a maximum of 4 characters.

Important: This module uses two sets of RTC memory slots, 10-20 for its control block, and a variable number of slots for samples and sensor names. By default these span 32-127, but this is configurable. Slots are claimed when rtcfifo.prepare() is called.

####See also

  • [rtcmem module]
  • [rtctime module]

rtcfifo.prepare([table])

####Description Initializes the rtcfifo module for use. It takes an optional configuration table as an argument. The following items may be configured:

  • interval_us: If wanting to make use of the rtcfifo.sleep_until_sample() function, this field sets the sample interval (in microseconds) to use. It is effectively the first argument of rtctime.dsleep_aligned().
  • sensor_count: Specifies the number of different sensors to allocate name space for. This directly corresponds to a number of slots reserved for names in the variable block. The default value is 5, minimum is 1, and maximum is 16.
  • storage_begin: Specifies the first RTC user memory slot to use for the variable block. Default is 32. Only takes effect if storage_end is also specified.
  • storage_end: Specified the end of the RTC user memory slots. This slot number will not be touched. Default is 128. Only takes effect if storage_begin is also specified.

Calling rtcfifo.prepare() unconditionally re-initializes the storage - any samples stored are discarded.

####See also

  • [rtcfifo.ready()]

####Example

rtcfifo.prepare() -- Initialize with default values
rtcfifo.prepare({storage_begin=21, storage_end=128}) -- Use RTC slots 19 and up for variable storage

rtcfifo.ready()

####Description Returns non-zero if the rtcfifo has been prepared and is ready for use, zero if not.

####Example

if not rtcfifo.ready() then -- Prepare the rtcfifo if not already done
  rtcfifo.prepare()
end

rtcfifo.put(timestamp, value, neg_e, name)

####Description Puts a sample into the rtcfifo. The timestamp would typically come from rtctime.get(). The effective value stored is valueE<sup>neg_e</sup>. Only the first four (ASCII) characters of name are used.

Note that if the timestamp delta is too large compared to the previous sample stored, the rtcfifo evicts all earlier samples to store this one. Likewise, if name would mean there are more than the sensor_count (as specified to rtcfifo.prepare()) names in use, the rtcfifo evicts all earlier samples.

If the rtcfifo has not been prepared, this function does nothing.

####Example

local sample = ... -- Obtain a sample value from somewhere
rtcfifo.put(rtctime.get(), sample, 0, "foo") -- Store sample with no scaling, under the name "foo"

rtcfifo.peek([offset])

####Description Reads a sample from the rtcfifo. An offset into the rtcfifo may be specified, but by default it reads the first sample (offset 0). The values returned match the input arguments used to rtcfifo.put().

If no sample is available (at the specified offset), nothing is returned.

####Example

local timestamp, value, neg_e, name = rtcfifo.peek()

rtcfifo.pop()

####Description Reads the first sample from the rtcfifo, and removes it from there. The values returned match the input arguments used to rtcfifo.put().

If the rtcfifo is empty, nothing is returned. ####Example

local timestamp, value, neg_e, name = rtcfifo.pop()

rtcfifo.drop(num)

####Description Discards up to num samples from the rtcfifo. If num is greater or equal to the number of samples currently stored, the rtcfifo will be empty on return.

####Example

rtcfifo.drop(2) -- Discard the first two samples in the rtcfifo, if present

rtcfifo.count()

####Description Returns the number of samples currently stored in the rtcfifo.

####Example

while rtcfifo.count() > 0 do
  local timestamp, value, neg_e, name = rtcfifo.pop()
  -- do something with the sample, e.g. upload to somewhere
end

rtcfifo.dsleep_until_sample(minsleep_us)

####Description When the rtcfifo module is compiled in together with the rtctime module, this convenience function is available. It allows for some measure of separation of concerns, enabling writing of modularized Lua code where a sensor reading abstraction may not need to be aware of the sample frequency (which is largely a policy decision, rather than an intrinsic of the sensor). Use of this function is effectively equivalent to rtctime.dsleep_aligned(interval_us, minsleep_us) where interval_us is what was given to rtcfifo.prepare().

####Example

rtcfifo.dsleep_until_sample(0) -- deep sleep until it's time to take the next sample

####See also

  • [rtctime.dsleep_aligned()]
Add a custom footer
Add a custom sidebar
Clone this wiki locally