cLog Lua ExtensionsA Short Reference

Acknowledgments

Lua is a wonderful scripting language. We thank Roberto Ierusalimschy s and the Lua community for for making it possible. I would also like to thank Matthew Percival for his contributions to much of the Capgo s embedded code that has extended Lua to support our very specialized hardware.

Graham HenstridgeCapgo Pty Ltd

draft

cLog extends Lua by adding a series of libraries. These either interact with the DAQ Engine or, provide advanced mathematical or communications capability. Some of these libraries are built into the cLog application, others (such as plot.lua, mail.lua, gps.lua and gsm.lua) are dynamically linked and may be used with the standard lua interpreter. The libraries assume the OS is embedded Linux.

DAQ Engine LibraryAlso see the config libraryengine.verbose ( [verbosity] )

Returns and optionally sets verbosity 0 to 10, default 3engine.dofile ( filename )

Loads and run lua chunk filename found in standard location /etc/capgo/

engine.calib ( )Initiates the initializationengine.calAdcTime ( )

Simulates the action required by the RTC or GPS one second interrupt that calibrates the adc sample counter to realtime. Should be in ~1s loop.

engine.scan ( )Single pass of the DAQ engine

engine.analog ( [power_level] )Returns the status of analog subsystem. Optionally sets power_level to “off”, “half” or “full”.

engine.gps ( [power_level] )Returns the status of the GPS sub-system. Optionally sets power_level to “off”, “half” or “full”.

engine.gsm ( [power_level] )Returns the status of GSM/GPRS modem. Optionally sets power_level to “off”, “half” or “full”.

engine.pstn ( [power_level] )Returns the status of the PSTN modem sub-system. Optionally sets power level “off”, “half” or “full”.

Engine function examples

CPU Librarycpu.setRtc ( t )

Sets hardware real time clock time-date as time-table tcpu.getRtc ( )

Returns hardware real time clock time-date as time-table, or nil and error message.

cpu.setRtcAlarm ( t )Sets hardware real time clock wake-up alarm to time-date as time-table t

cpu.getRtcAlarm ( )Returns hardware real time clock wake-up alarm time-date as time-table, or nil and error message.

cpu.setReg ( addr, size, val )Dangerous - mistakes can be catastrophic! Not recommended. Writes val to physical address addr which is assumed to be of size (8, 16 or 32 bits).

cpu.getReg ( addr, size )Returns value at physical address addr which is assumed to be of size (8, 16 or 32 bits).

cpu.snooze ( )Puts the system into a lower power mode that takes about 10μs to exit. Battery current 100mA.

cpu.sleep ( )Puts the system into a low power mode. Requires approx 50ms to wake. Battery current 4mA

cpu.coma ( )Puts the system into a power-down mode. Takes 10 seconds to power-up and reboot. Battery current 200μA

Schedules LibraryThe timing of activities in cLog are managed by schedules that are maintained in a dynamically ordered linked list. Each schedule has a set of properties:

name schedules name of any reasonable lengthaction item name that is to be controlledperiod repeat period between starts of the schedule in

seconds (1 to 1,000,000+ seconds)duration active duration in seconds (1 to 1,000,000+

seconds or 0 for continuous (default))offset an offset in seconds from midnight in calculation

of first start time (default = 0)priority numeric: 0-10 or text: “max”=1,”high”=3,

“medium”=5, “low”=7, “none”=9.enable enabled state 1 = enabled (default), 0 = disabledtype numeric: 1-3 or text: “waterfall”=1 (default),

“engine”=2, “control”=3 schedule start time (second since epoch) of next active state or

time-table (see the OS Library)delay A pseudo property, in seconds, used to set the

start property to a time delayed from now.schedule.create ( definition_table )

Creates a schedule list from a passed definition_table:{ schedule_name1 = { prop1=val1, prop2=val2 ... }, schedule_name2 = { prop1=val1, prop2=val2 ... }, ... }

Identical to config.schedules ( ).schedule.add ( n, a, r, [d, [o, [p, [e, [t ]]]]] )

Adds new schedule of name n, action a, period p, duration d, offset o, priority p, enable state e and type t. Returns 1, or nil and an error string.

schedule.remove ( n )Removes named schedule n from schedule list. Actions initiated by schedule continue for duration or until aborted. Returns 1, or nil and error.

schedule.modify ( name, property, value )Sets name named schedule property to value. Returns 1, or nil and error string.

schedule.run ( )Runs scheduler. Normally placed in main acquisition loop. Returns the number of seconds to next schedules start time.

schedule.abort ( )Abort current schedule s action, although may run through to natural completion to ensure orderly data management. Returns 1, or nil and error string.

schedule.delete ( )Deletes the entire schedule list. Any schedule actions that may have been initiated will duration time or until aborted. No return value.

schedule.print ( )Prints schedule list in tabular format. For debugging or documenting scripts. No return value.

Schedule function examples

Sensors LibraryThe most common use of the sensor functions is in debugging a difficult problem. See the Appendix for supported sensor types.sensor.getProp( sensor_name, property )

Returns value of named sensor s property or if an error, nil and error message. Properties are:

type - supported sensor type.scale - scale factor to convert to SI units.offset - offset factor to convert to SI units.timeConstant - sensor s response time in seconds.exciteValue - target excitation value.refText - name of reference tag or variable

resistance - the R0, R25 or bridge resistance value.

cLog Extensions Short Reference

Rref - value of reference resistor ( ).var - a variable used by some sensor types.dac - the hex value of the initial 32 bit dac word that

controls excitation and sensor power.mux - the hex value of 32 bit multiplexer word.muxInv - the hex value of inverted multiplexer.

Not all properties are meaningful for all sensors.sensor.setProp ( sensor_name, property, value )

Set sensors properties. Some properties are only used to provide defaults for tag configuration. Take care, the dac property has potential to damage some sensors by applying excessive excitation or power.

sensor.print ( )Prints defined sensors. For documentation and debug.

sensor.printParameters ( )Prints parameters. For documentation and debug.

sensor.printSystem ( )Prints system properties. For documentation and debug.

sensor.printSmart ( )Prints smart sensors. For documentation and debug.

sensor.printEngine ( )Prints engine properties. For documentation and debug.

sensor.printGroups ( )Prints sensor groups. For documentation and debug.

sensor.thermocouple ( type, voltage, reference_temp )Returns temperature in °C of thermocouple of type B, C, D, E, G, J, K, L, M, N, P, R, S, T, or U from voltage (volts) and junction reference_temp (°C). On error, returns nil and error message.

sensor.rtd ( type, Rt, Ro )Returns temperature in °C of RTD of type Pt385, Pt392, Cu427, NiFe518 or Ni672, with a resistance Rt and resistance of Ro at 0°C. (Rt and Ro same units).

sensor.thermistor( type, Rt [, R25] )Returns temperature in °C of YSI standard thermistors L100, L300, L1K1, B2252, B3K, B5K, B6K, B10K, H10K, H30K, H100K, H300K or H1M, with a resistance Rt. If R25 value passed, it is used in preference to thermistor type s standard R25 value.

Sensor function examplessensor.thermocouple( “T”, 0.00150, 25.5 )

returns 61.02 °C.

Tag LibraryTags are the main data collection structure and focus of the DAQ Engine. They are created at config time.tag.get ( )

Returns currently defined tags and returns them in an indexed table array, or nil and error message.

tag.value ( tag_name )Returns tag_name s latest good value with it s time-stamp string, or nil and error message. If the tag has not yet produced data it returns nan.

tag.getArchive ( n, st, d, p [, i] )Returns table of time-series historic data for tag n, from start time table st, for duration d with a period p between samples. If gaps in data, nan s inserted according to the tag s stripNANs property:

0 do not strip any nan s1 strip leading nan s2 strip trailing nan s (default)3 strip both leading and trailing nan s

Optionally, an interpolation method i, may be defined:0 use the value at an equal or prior time to the

requested time (initial default)1 use a linear interpolation between a value

on either side of requested timeThe start_time_table uses standard lua time definition. Errors return nil, error message and an error number:

1 tag not found2 tag has no archiven ... TODO

tag.getBlockArchive ( n, st [, max] )Return historic block-data for tag n, as a table array of data points and the number of points in the table. The data is the first non-time-series data block found from the time specified st. Optionally, max sets the max. number of data points returned (default to tag s terminating pipe size). If no data is found, empty table returned. Errors return nil and an error message.

tag.mergedArchivesFile ( tg, fn, st, d, p [, f] )Creates a file fn of chronologically merged data from qualified tags in tagGroup tg (a table of tags or a named group), over duration d with a re-sample period p. Returns number of qualified tags and number of data rows or nil and error message. To qualify, tag must have time-series archive. File fn placed in the base of project s log directory. Format f may be defined as an attribute table:separator - defines the data field separator

coma coma placed between data items tab tab placed between data items (default)

type - defines the output file typeascii human readable file format (default)binary compact machine readable file format

see Binary File Format Note (TN1000)compress - defines the compression to be applied

none no file compressionbzip2 apply bzip2 compression on file

time - defines the time-stamp formatnone no time-stamp is insertedfull full date and time at row beginning e.g.

2006-11-01 15:03:49.099990 short date and time at row beginning e.g.

2006-11-01 15:03:49time time at row beginning e.g.

15:03:49.099990sec seconds of minute at row beginning e.g.

49.099990The default is determined from the tag period - if sub-second then full, otherwise short.

terminate - defines the line terminating characterslinux places a LF at end of line (default)mac places a CR at end of linewin places CR LF at end of line

tag.mergedArchives ( tg, st, d, p [, f] )Returns table of chronologically merged tag data, number of qualified tags and number of data rows. Data selection as for tag.getArchive ( ). The data table has the following form:{ {startTime = time, period = value, tags = { tag_list },

{ [time_1,] tag_1_data, tag_2_data, ... tag_n_data },{ [time_2,] tag_1_data, tag_2_data, ... tag_n_data },

...{ [time_t,] tag_1_data, tag_2_data, ... tag_n_data }

}Format f is as in tag.mergeArchivesFile()

except only time format attribute is meaningful. tag.flush ( )

Flushes all tag archive buffers to disc. tag.getProp ( tag_name, property )

Returns the nominated tag property or in case of an error, nil nil and an error string. Properties:inputType Number representing input source.input Input source name.parameter Measurement parameter name.recipe Process recipe name.scale Scale factor applied to raw tag input by

scale step (default from sensor).offset Offset factor applied to the raw tag input

by scale step (default from sensor).timeConstant Time constant in seconds (default from

measurement parameter).period Actual scan period of the input in sec.

draft

page 2 of 10

errorBound Error bounds applied duringcompression. In tag s units.

refTemp Name of tag used as reference.closeAccum State of the close off accumulation flaginterpolation Defines current archive data extraction

method (see tag.getArchive() )stripNANs Strips leading and trailing nan s from a

time-series extracted from an archive (see tag.getArchive() )

tag.setProp( tag_name, property, value )Sets property of tag_name to value. Returns 1, or nil and error string. Properties are:name Name of the tag.scale Scale factor applied to the raw tag input

(default from sensor).offset Offset factor applied to the raw tag input

(default from sensor).timeConstant Time constant in seconds (default from

measurement parameter).period Scan period of the input in seconds.errorBound error bounds for compression.refTemp Name of the tag for a reference channelcloseAccum State of the close off accumulation flaginterpolation Sets default archive data extraction

method (see tag.getArchive() ).stirpNANs Strips leading and trailing nan s from a

time-series extracted from an archive (see tag.getArchive() ).

Setting properties need to be done with care as impact can be delayed.

tag.stats ( [tag_name] )Return cpu usage estimates. If tag_name not passed, returns a table of tag_name cpu percentage pairs and number of table entries. If a valid tag_name is passed, returns cpu percentage for tag. Otherwise a nil and error message is returned.

tag.closeAccumulation ( tag_name | tag_group )Closes all accumulation processes. Return number tags closed,

or nil and error message.tag.setFilterProp ( tag_name, filter_num, property, value )

Set bi-quad filter filter_properties. Tag may have any number of cascaded filters, numbered from 1. The function sets property of filter_num in tag_name s recipe to value and returns 1, or nil and an error string. The valid properties are:type sets the filter type: "low_pass",

"high_pass", "band_pass", "notch", "peaking_band_pass", "low_shelf", "high_shelf".

centerFreq sets the center frequency in hertz.bandwidth sets the filter s bandwidth in hertz.sampleRate sets the filter s perceived input sample

rate.tag.getFilterProp ( tag_name, filter_num, property )

Returns the value of property of filter_num in tag_name s recipe, or nil and error string. The properties as in tag.setFilterProp().

tag.resetFilters ( )Re-calculates coefficients of all filters according to tag s sample rate. Returns the number of filters recalculated (Done automatically when adc sample rate modified).

tag.create ( tag_definition_table )Builds the tag list from a passed table of tag properties. Identical to the config.tags() function and should not normally be used after configuration.

tag.createGroups ( tag_group_list_table )Builds the tag group list from a passed table. Identical to the config.tagGroups() and can be applied at any time.

tag.forceFeed ( tag, { n | t | v } [, p [, dt]] )Force feed data into tag s input buffer for debugging. The data source is either a single number n, table of numbers t or a named vector v. The optional period p forces the data packet s period value. The optional

data_type dt can be blockdata or timeseries (the default), and forces the data packet to be marked as block data or time-series data. Returns number of values forced, or nil and error message. A blocked tag will generate an error.

tag.print ( [tag_name] )If no passed parameter, prints tag list by name and latest values in a tabulated format. If a valid tag_name is passed it prints the latest value for that tag.

tag.printDetails ( )Prints the tag list details in a tabulated format. The detail is excessive for most purposes.

tag.printAlams ( )Prints the alarm list in a tabulated format.

tag.printGroups ( )Prints the tag groups in a tabulated format.

tag.printRecipes ( )Prints the tag groups in a tabulated format.

tag.printPlumbing ( )Prints the tag groups in a tabulated format.

tag.printArchBuff ( tag_name )Prints a tag_name s archive buffer. For debugging.

Tag function examples

Alarms LibraryAn alarm is a condition in which a tag s data stream moves outside lower and upper thresholds for more than a certain time. Alarms are defined in a tag s recipe. An alarm can be identified in three ways.

By tag name - first defined alarm of tag.By tag name and alarm name - uses first matching

alarm name in tag.By tag name and alarm number - refers to the indexed

alarm. This method is least ambiguous.Use the method that is not ambiguous for you configurationalarm.next ( [“ack”] )

Returns next highest priority alarm as four values: alarm name, tag name, alarm number and the present alarm state (see alarm.state() ). If no alarms, returns nil. Alarm acknowledged if “ack” passed.

alarm.ack ( tag_name, [{ alarm_name | alarm_number }] )Acknowledges alarm associated with tag_name or optionally alarm_name or alarm_number. Returns the number of cycles from normal to alarm state since previous acknowledgment, or nil and error message.

alarm.getAll ( )Returns a prioritized table array of all defined alarms.

alarm.getActive ( )Similar to alarm.getAll( ) except it returns a prioritized table array of all unacknowledged alarms,

alarm.state ( tag_name, [{ alarm_name | alarm_number }] )Returns alarm state of tag_name or a specific alarm_name or alarm_number and returns the state number and descriptive text or, nil and error message. The alarm s states are:State Descriptive text Exit to State 0 normal < low(1) OR > high(4) 1 pending low > low(0) OR time-out(2) 2 low alarm > low + hysteresis(3) 3 low, pending normal < low(2) OR time-out(0) 4 pending high < high(0) OR time-out(5) 5 high alarm < high - hysteresis(6) 6 high, pending normal > high(5) OR time-out(0)Pending states have crossed alarm threshold but not spent sufficient time there to qualify as an alarm.

alarm.setProp ( tn, {0 | n | no }, p, v )Sets property p associated with tag tn or a specific alarm name n or alarm number no to a value v. Properties:lowThreshold Sets the low alarm threshold.hightThreshold Sets the high alarm threshold.

draft

page 3 of 10

hysteresis Sets the hysteresis band.response Sets the response time in seconds.priority Sets the alarm priority 0 to 100

(higher numbers = higher priority).name Sets the alarm name to value string.state Sets the alarm state.On on success returns 1, or nil and an error message.

alarm.getProp ( tn, { 0 | n | no }, p )Complement to alarm.setProp( ) and provides for reading same set of alarm properties. Returns property value, or nil and error message.

alarm.clearAll ( )Clears all alarms sets alarm state to 0. Time response delays will apply. A brutal function and best not used as lazy way of acknowledging.

alam.printAll ( )Prints the alarm list in a tabulated format.

Alarm function examples alarm.setProp( “Boiler_Temp”, 0, “name”, “Over_Temp” )sets the name of the first alarm of the “Boiler_Temp” tag to

“Over_Temp”.alarm.setProp( “Fuel_Level”, 0, “ lowThreshold”, 25.0 )sets the Fuel_Level tag s lower alarm threshold to 25.0.

Fusers LibraryFusers are a class of tag input that fuses multiple sources in some way that creates a single input data stream. fuser.create ( fuser_definition_table )

Creates a new set of data fusers from the passed fuser_definition_table.

fuser.opList ( definition_table )Returns a list of valid fuser operation codes.

fuser.print ( )Prints the fuser list in a tabulated format. No returns.

Variables LibraryThe DAQ Engine supports named variables that must be declared at configuration time. These are not Lua variables. Tag recipe operations are able to quickly read and write to these variables during background execution. var.set ( variable_name, value )

Sets variable_name DAQ Engine variable to value. Returns 1 if successful otherwise nil and an error message.

var.get ( variable_name )Returns DAQ Engine variable_name, or nil and error message.

var.create ( descriptive_table )Attempts to define a set of variables from descriptive_table. Returns 1, or nil and error message. This function is identical to config.variable(). Should not be called after configuration.

var.print ( )Prints to stdio a tabulated list of variables. There is no return value. For debugging and documentation.

Vector Math LibraryMath functions that operate on first parameter that must be a table array and for some, a second parameter that may be a number or a second table array. Results returned as a table array with the size of smaller of passed tables. If the arguments not sensible, a nil and an error message is returned.vector.invert ( table_array )

Inverts (i.e. 1/x) each member of table_arrayvector.square ( table_array )

Squares (i.e. x2) each member of table_arrayvector.squareRoot ( table_array )

Square root (i.e. x0.5) of each member of table_arrayvector.absolute ( table_array )

Absolute value (i.e. |x|) of each member of table_array

vector.log10 ( table_array )Log base ten of each member of table_array

vector.10log10 ( table_array )Ten times log base ten of each member of table_array

vector.20log10 ( table_array )Twenty times log base ten of each member of table_array

vector.expand ( table_array )Inverts (i.e. 1/x) each member of table_array

vector.add ( table_array_1, { table_array_2 | number } )Adds table_array_2 to table_array_1 or adds number to each element of table_array_1.

vector.subtract ( table_array_1, { table_array_2 | number } )Subracts table_array_2 from table_array_1 or subtracts number to each element of table_array_1.

vector.multiply ( table_array_1, { table_array_2 | number } )Multiplies table_array_2 by table_array_1 or multiplies each element of table_array_1 by number.

vector.divide ( table_array1, { table_array_2 | number } )Divides table_array_1 by table_array_2 or divides each element of table_array_1 by number.

vector.clip ( vector_name, lower_limit, upper_limit )Clips the vector_name to values between lower_limit and upper_limit. Returns percentage of values clipped, or if an error occurs, nil and an error message.

vector.toTable ( vector_name )Returns a DAQ Engine vector (vector_name) as a table array and its size. If an error occurs, returns nil and an error message.

vector.fromTable ( source_table, vector_name )Loads a DAQ vector vector_name from a passed table array source_table. Returns the number of elements transfered, or nil and error message.

vector.getElement ( vector_name, element_index )Returns the vector element at position element_index of DAQ vector vector_name, or nil and error message.

vector.setElement ( vector_name, element_index, value )Sets the element_index of DAQ vector_name to value. Returns 1, or nil and error message.

vector.print ( [vector_name [, offset [, number]]] )With no arguments, prints the first ten items of all defined vectors. If a valid vector_name is passed, it prints the first ten items of the named vector. If an offset is passed then ten item from the offset will be printed. If a number is passed, then that number of elements is printed. If an error occurs, returns nil and an error message, otherwise nothing.

Statistical LibraryThe statistical functions all operated on an table array. The contents of the passed input data table array are replaced by the results. Any undefined numbers (i.e. not a number nan or NAN) are generally ignored but ± infinity are considered valid and propagated through. Should an error occur nil and an error message are returned.stats.stats ( table_array )

Returns a table array of summary statistics of the passed table_array in the following order: mean, maximum, minimum, variance, coefficient of variance, standard deviation, root mean square and number of valid values on table array.

stats.mean ( table_array )Returns arithmetic mean of all array values excluding those marked as not a number (NAN)

stats.max ( table_array )Returns maximum value found in table_array

stats.min ( table_array )Returns the minimum value found in table_array

stats.var ( table_array )Returns variance of the values in table_array

stats.cv ( table_array )Returns coefficient of variance of values in table_array.

draft

page 4 of 10

stats.sd ( table_array )Returns standard deviation of values in table_array.

stats.rms ( table_array )Returns the root mean square of values in table_array.

stats.n ( table_array )Returns the number of valid values in table_array.

Statistical function examples

Spectra LibraryTake a table array of data, apply transformation and return a table array of results. Typically returned array is different size to the input array. If input array size is not a power-of-two, then it is converted to a power-of-two, with symmetrical padding of zeros.spectra.FFT ( table_array )

Applies a real discrete Fast Fourier Transform to input table_array, returning an amplitude spectra.

spectra.pwFFT ( table_array )Applies a real discrete Fast Fourier Transform to input table_array, returning in power spectra.

spectra.logPwFFT ( table_array )Applies a real discrete Fast Fourier Transform to input table_array, returning the log10 power spectra.

spectra.cepstrum ( table_array )Returns a cepstrum: applies a real discrete FFT on table_array to produce power spectra. A log10 is applied then another FFT.

spectra.goertzel ( table_array_1, table_array_2 )Applies a Goertzel transformation to table_array_1 at the frequencies listed in table_array_2, and returns the coefficients of the transformation in a table-array of the same size as table_array_2. The table_array_1 is expected to contain the sampling period in seconds (e.g.table_array_1[“period”] = 0.0001).

spectra.nextPowerOf2 ( table_array )Returns a table array enlarged to the next higher power of two, and places the input table_array data in the center of the new array, padding the beginning and end with zeros.

Spectra function examples

Window (Shaping) LibraryWindow shaping applies amplitude shaping to a table array with aim of reducing “end effects” on spectral transformations.window.bartlett ( table_array )

Returns a copy of table_array with a Bartlett (or Triangle) window applied.

window.hanning ( table_array )Returns a copy of table_array with a Hanning window applied.

window.blackman ( table_array )Returns a copy of table_array with a Blackman window applied.

window.blackmanExact ( table_array )Returns a copy of table_array with a Harris-Blackman window applied.

window.harrisBlackman ( table_array )Returns a copy of table_array with a Harris-Blackman window applied.

window.flatTop ( table_array )Returns a copy of table_array with a Flat Top window applied.

window.blackmanOptimal ( table_array )Returns a copy of table_array with a Blackman Optimal window applied.

window.welsh ( table_array )Returns a copy of table_array with a Welsh window applied.

Psychrometric Librarypsycho.humidity ( dry_bulb, wet_bulb [, elevation] )

Returns relative humidity (%) based on wet_bulb and dry_bulb temperatures (°C) & elevation (default 0m).

psycho.dewpoint ( dry_bulb, wet_bulb [, elevation] )Return dew point (°C) based on wet and dry bulb temperatures

(°C) & elevation (default 0m).psycho.windchill ( windspeed, temperature )Returns windchill from windspeed (kph) and temperature (°C)

according to JAG/TI Committee.psycho.heatIndex ( temperture, relative_humidity )Returns heat index from temperture (°C), and

relative_humidity (%)psycho.elevationToPressure ( elevation )

Returns standard pressure (kPa) at elevation (m) psycho.windGradient ( speed_10m, height [, roughness] )

Returns wind speed correction at height (m) based on wind speed at 10 m speed_10m (m/s) and surface roughness in m (default 0.1m).

Modbus LibraryThe five basic Modbus i/o types are supported: discrete 1 bit output (0xxx) discrete i bit input (1xxx) 16 bit register output (4xxx) 16 bit register input (3xxx) file/extended read/write (6xxx) modbus.create ( definition_table )

Defines the modbus registers and mapping between registers and tags, variables and vectors. It is usually only called during the configuration phase. Using the function at other times may create ripple through problems. The passed definition_table has the form:definition_table = { { regxxxx | regFxxxx } = { [num_of_reg], [name_1 [,

name_2 [, name_3] .... ]]] } .... }

where:regxxxx Starting register number that also

defined the register type (i.e. the first digit of the xxxx as described above).

regFxxxx Starting register number of register pairs that represent floating point numbers. Range is limited to 3000 to 4999.

num_of_reg Optional indicator of number of sequential registers to be created.

name_x Named tag, variable or vector. Allocated registers from starting address.

Note that registers can be created that are not linked to a tag, variable or vector.

modbus.print ( )Prints a summary of configured modbus resisters.

modbus.setReg( register_address, value )Loads the modbus register at register_address with value. Returns 1, or nil and error message.

modbus.getReg( register_address )Returns value the modbus register at register_address, or nil and error message

modbus.setVector ( start, size, table_name )Loads sequential modbus registers starting at start with values passed in table table_name. The number loaded is the smaller of size, num. of elements in table_name or number of sequential modbus registers from start. Returns 1, or nil and error message.

modbus.getVector ( start, size )Returns a table with values from sequential modbus registers starting at start_register_address. Number loaded is smaller of size and num. of sequential registers from start_register_address. Returns nil and an error message on failure.

modbus.status ( )Returns a table of modbus status values.

draft

page 5 of 10

modbus.property ( property_name [, value] )Returns and if value is passed sets, a property of the modbus slave, or nil and error message. Properties are:delimiter sets the acsii delimiter character to

value interpreted from a decimal numbermessage slave message countexception slave exception error countresponse slave no response countnak slave nak (not acknowledged) countbusy slave busy countoverrun slave bus character overrun countiop IOP overrun countflags clears flags

Most of these properties are available to the modbus master.

Modbus function examples

Plot LibraryThe plot.lua module s plot functions utilize gnuplot and are optimized by their plot type to produce a png image. Appearance is determined by cascading style sheets. While each variable must share same set of axis and range, each can have a different plot type. By default, plot images are placed in /usr/www/plot/ for website use. From there, plots can be emailed as attachments or display on the LCD if fittedTo reduce cpu requirements, plots are not anti-aliased. However some browsers anti-alias well if the image is oversized and reduced in the html tag.Due to numerical intensity of plot generation, the action is hived off to a background process to avoid blocking the main line program. Typically a 100 point plot will take about 1 second to generate.

Plot Typesplot.trend ( data_source, labels, range, [style] )

Trend plot with x-axis time in default format. Default style is “style-trend”. The data_source requires 2 columns of data per plot.

plot.line ( data_source, labels, range, [style] )General purpose line plot. Default style is “style-line”. The data_source requires 2 columns per plot.

plot.point ( data_source, labels, range, [style] )General purpose point plot. Default style is “style-point”. The data_source requires 2 columns per plot.

plot.linepoint ( data_source, labels, range, [style] )Lline plot. Default style is “style-linepoint”. The data_source requires 2 columns per plot.

plot.errorbar ( data_source, labels, range, [style] )Points plot with error bars. Default style is “style-errorbar”. The data_source requires 3 or 4 columns per plot. If three columns provided, third column is the delta value. If four columns, the third column is minimum y-value and fourth column maximum y-value.

plot.scatter ( data_source, labels, range, [style] )Scatter plot for many points. Default style is “style-scatter”. The data_source requires 2 columns per plot.

plot.spectra ( data_source, labels, range, [style] )Optimized for plotting spectra. Default style is “style-spectra”. The data_source requires 2 columns per plot.

plot.histogram ( data_source, labels, range, [style] )Plotting a histogram. Default style is “style-histogram”. The data_source requires 1 or 2 columns per plot.

plot.polar ( data_source, labels, range, [style] )For plotting a polar plot. Default style is “style-polar”. The data_source requires 2 columns per plot.

plot.vector ( data_source, labels, range, [style] )Plots of vectors represented as arrows. Default style is “style-vector”. The data_source requires 2 columns (i.e. mx/n) of data per plot.

plot.surface ( data_source, labels, range, [style] )Plots a 3D surface. Default style is “style-surface”. The data_source requires multiple blocks of 2 column data as sequential 2D data x-z blocks separated by single blank line.

plot.multiplot (data_source,labels,range [,style] [, columns])Plots multiple plots in a single image file. Plots arranged in columns, the number of which are defined by columns, and start top left. Default style is “style-multiplot”. The data_source requires 2,3 or 4 data columns per plot.

plot.plotting ( )Returns true if the plotting engine is busy, or false. Always test before generating a new plot.

Plot function argumentsThe primary plot functions all have the same form, arguments, and return value. plot.xxxx ( data_source, labels [, range [, style]] )

where xxxx is plot type and arguments are described below. The return value is a string with the name of the image file, or nil and error message. The file is placed in the /tmp/ directory. Pre-existing files are over-written.

Details of the function arguments are as follows:data_source

The data_source is a table of nested tables specifying data files, preferred plot types and optionally their column mapping. The table format is:{ { dataset=”label/1“, file=”file/1”, plot=”plot_type/1”, m1/1, m2/1, m3/1, m4/1, m5/1, m6/1 },

{ dataset=”label/2“, file=file/2”, plot=”plot_type/2”, m1/2, m2/2, m3/2, m4/2, m5/2, m6/2 },....

{ dataset=”label/n“, file=”filen”, plot=”plot_type/n”, m1/n, m2/n, m3/n, m4/n, m5/n, m6/n } }

where:dataset

Optional name of the data set and parameter being plotted. Used in a legend when more than one data set plotted. Defaults to Plot1, Plot2 etc.

fileName of the file containing parameter data (see below)

plotOptional “raw” plot types and number of data columns: Type Data Commentslines 2 Adjacent points connected

by linespoints 2 Points as a small symbollinespoints 2 Combination of lines and

pointsimpulses 2 Line from point to x-axisdots 2 Small dot for each pointsteps 2 Adjacent points connected

by horizontal the vertical lines

fsteps 2 Adjacent points connected by vertical then horizontal lines

errorbars 3, 4 As for points except vertical error bar displayed

yerrorbars 3, 4 Same as errorbarsxerrorbars 3, 4 Same as yerrorbars except

the error bar is horizontalxyerrorbars 4, 6 Combination of xerrorbars

and yerrorbarsboxes 2, 3 For bar-charts, with third

column box widthhisteps 2 For histogramsboxerrorbars 4, 5 Combination of boxes and

yerrorbarsboxxyerrorbars 4, 6 similar to xyerrorbars

except error box displayed

draft

page 6 of 10

candlesticks 4 Opening, high, low and closing values

financebars 4 Similar to candlesticks, but different graphics

vector 4 Arrow from (x,y) to (x+ x, y+ y)

mx/n Column from which data is mapped for plot type.

The data file format is rows and columns organization with space separated ascii numbers. For trend plot types with a time or date axis, it is assumed the time format is either hh:mm, hh:mm:ss or DD/MM/YYYY.

labelsPlot labels are passed in a keyed table:

{ title = “Vibartion Change with Time”, xlabel = “Time (days)”, ylabel = “Magnitude (m/s/s)” file = “vibration” }

The title is placed top mid center of the plot. A nil value will suppress it. The x and y labels are placed on the appropriate axis or boarder. The labels defined by the set title, set xlabel and set ylabel commands in style sheet. If plot file name not provided, then plot s title is used and if that not defined, “plot” is defaulted.

rangeRange defined by table containing axis limits:

{ x_min, x_max, y_min, y_max }If passed a nil, or table nonsensical, then auto scales.

styleStyle sheet (see “Style Sheets” below) or style table. If omitted, uses plot type s default.

Data File FormatA data file requires a white-space separated column organization of ascii data, with rows representing one or more points. Comments from # to the end of line. For 2D plots single blank line indicates discontinuity in the data. Double blank lines indicate a block junction that requires the index option in the plot command.3D surface data is divided vertically into single blank line separated blocks, each representing an x-z plot.

Plot Style SheetsStyle sheets are a set of plot commands that determine the appearance of a plot. Each plot type has its default style sheet that has a “style-” prefix to the plot type (e.g. “style-point”). Style sheets are placed in /usr/local/share/gnuplot/4.0/.

CascadingStyle sheets can be cascaded - meaning one sheet can invoke another - by using the #include filename or the #default commands at beginning of a line. Avoid circular references. A set of styles common to all default styles is contained in the “style-master” style sheet. Plot type default style sheets #includes style-master in first line.The #default command inserts the default sheet for plot type.

Passing a style sheet in a tableA style sheet may be passed to the plot directly via the style argument. If a style argument is a table, each line is in quotes and comma separated:

{ “#include style-common”, “set bmargin 4 “set format x \”%M:%S\” ” }

If quotes are required within the command they must be “escaped” with a backslash as in the above example \”%M:%S\” which results in ”%M:%S” .

Text substitution via style sheetsStyle sheets may also contain text substitution markers, namely:

#title Replaced by the plot s title text#xlabel Replaced by the plot s x-label text#ylabel Replaced by the plot s y-label text

Fonts

The plot generator utilizes scalable TrueType fonts (located in the directory /urs/share/fonts/TrueType). The available fonts are:Font Name Samples (in 8 pt)FreeMono abc ABC 1234567890 μ ß ƒ

FreeMonoOblique abc ABC 1234567890 μ ß ƒ

FreeMonoBold abc ABC 1234567890 μ ß ƒ

FreeMonoBoldOblique abc ABC 1234567890 μ ß ƒ

FreeSansOblique abc ABC 1234567890 μ ß ƒ

FreeSansBold abc ABC 1234567890 μ ß ƒ

FreeSansBoldOblique abc ABC 1234567890 μ ß ƒ

FreeSerifOblique abc ABC 1234567890 μ ß ƒ

FreeSerifBoldOblique abc ABC 1234567890 μ ß ƒ

Advance formatingop code does action

^ x^y or x^{yz} xy or xyz superscript_ x_y or x_{yz} xy or xyz subscript@ phantom box & x&{5}y x y inserts spaces~ ~x{.8 } x over-prints\ \^ ^ escapeFont may also be changed mid stream:{ / [fontname] [=size | *scale ] text }

Plot function examples

GPS LibraryThe gps.lua functions support the built in GPS receiver module.

gps.get_position ( )Returns longitude (deg:min:sec), latitude (deg:min:sec) and altitude (m).

gps. get_time ( )Returns hours, minutes and seconds UTS

gps. get_date ( )Returns day, month and year UTS

gps. get_course ( )Returns present heading in deg from north

gps. get_speed ( units )Returns speed in (units = ) “kph” or “knots”

gps. get_dilution_of_precision ( )Returns position, height and velocity precision reduction

gps. get_satellite_information ( )Returns a table of satellite data including azimuth and signal to noise ratio.

gps.angle_to_number ( angle )Returns the passed angle in deg:min:sec format to a floating point number in deg.

Mail LibraryMost mail function spawn off a new process to avoid main loop blockage due to delays. The mail.lua module is essentially a wrapper around Diego Nehab s LuaSocket library and Capgo s mailsend.lua ( module ).

mail.boxes ( table )Defines mail in-boxes via table that contains mailbox_name (key) and subject_filter (value) pairs. Default = { root = “!!: ” }. Mail sorted on subject prefix string. Note: some characters in prefix string require “double escaping”, thus “!!: ” becomes “\\!\\!\\: ”. Function replaces the /etc/maildroprc file.

draft

page 7 of 10

mail.autorespond ( message )Acknowledges all received messages in the /tmp/ directory with message string. Prepends “Ack: “ to subject. To avoid re-acknowledgements, either move or rename “bodynn” files before next call. Appends “-- Acknowledged” or and “-- Error: “ and error message to bodynn file.

mail.sendsetup ( server, me [, timeout [, port]] )Sets up send mail details where:server Address of email server from which

email is collected.me Assigned mail address for unit.timeout In seconds, default 60 sec.port Server s port number (default 25).The defaults for these arguments is determined by system variables system.mailserv, system.mailport, system.my_address usually found in initialize.lua

mail.send ( recipients, title, message, html, attachment )Initiates sending an email by launching new process, where:recipients An email address string or a table of

email addresses.title Subject text.message Message text.html If true sends email in html format.attachment Table of attachment files. File extension

determines mime encoding.Returns 1 and message or nil and error message. Success indicates email constructed and forwarded to dispatcher. NOTE: There is no send queue - so can process only one mail (but can be to multiple destinations) at a time. Confirm sent with mail.checkifsent ( ) call before sending next mail.

mail.check ( )Checks status of mail system. Returns nil if no action required or a table of status data. Table can contain:key “ok_to_send” = true

if previous mail sent, timed out and a request to send has been rejected because system busy.

key “send_error” = error stringif last email failed.

array value = mailbox nameif mailbox contains incoming mail. The # operator indicates the number of mailboxes with unread mail.

mail.checkifsent ( )Returns 0 if email still being sent without timed out, 1 when complete, otherwise nil and an error string.

mail.receive ( [inbox] )Launches a new process and processes emails in mailbox inbox (default /var/spool/mail/root). Places emails and attachments in /tmp/ with file name of body00, body01 .. body99. The first line of body is subject, second line the from or reply to address. The mailbox is cleared. Remember, /tmp/ is erased on sleeping, so move files if to be retained. Returns number of emails received and number of attachments, or nil and an error message.

mail.checkreceived ( )Returns number of emails and attachments received by last call to mail.receive(), or nil and an error string.

Filtering EmailPrevent spam - apply filters via /etc/maildroprc. The default filters exclude known spam, virus, and mail without “!!:“ at start of subject field. Mail boxes can be defined here. See mail.box()

MIME IssuesSent mails are text/plain unless attachment added which will be encoded base64 or quoted-printable depending on the file extension. Received mails can be text/plain, base64 or quoted-printable, with or without attachments.

Email accountEmails received via fetchmail. Account info in /etc/fetchmailrc file which should contain:

poll mail_server_urlset daemon 60proto pop3user “name” with pass “password”, is guru hereno keep

where set daemon 60 set polling interval in seconds. Note: fetchmailrc needs root permissions to modify.

GSM LibraryThe gsm.lua functions are for use with internal GSM / GPRS module. They provide SMS message send and receive as well as high speed GPRS internet connection.gsm.init( pin )

Initializes the GSM modem using the SIM pin number. Returns true of success, or false.

gsm.read_sm( mesg_id )Returns keyed table of short message (with mesg_id id number), or nil. The table has keys message, phone, date and time.

gsm.send_sm( sca, phone, message )Sends a short message to phone number via service center address sca. Returns true on success, or false.

gsm.delete_sm( mesg_id )Removes message mesg_id from the message buffer.

gsm.gprs_dial( [script] )Establishes a GRPS connection. The optional script is substituted for the default script for dialing. Returns true if successful, or false.

Linux IssuesAll directories and files have an owner, belong to one or more user groups and have a set of permissions that describe what can be done.

Standard PlacesAs far as possible cLog places all files in standard Linux places. Non-standard places likely to incur permissions issues.

Script and configuration files/etc/capgo/

Lua user authored Lua modules/usr/share/capgo/

Data achieve/var/log/projectName/

Temporary data storage place /var/tmp/ User script must manage this directory to

avoid file accumulation./tmp/ A fast 1MB RAM disc, lost in sleep mode.

cLog executable/usr/bin/cLog cLog

cLog Lua modules and libraries/usr/share/lua/capgo/ cLog Lua modules/usr/share/lua/ supporting modules/usr/lib/ cLog Lua C libraries

Fonts/usr/share/fonts/TrueType/freefont/

Plot style sheetsusr/local/share/gnuplot/4.0/

Web siteusr/www/ web site base directoryusr/www/cgi-bin cgi (Lua) scriptsusr/www/plot/ plot images

UsersThere are ten predefined users that reflect job activity involved. Each has a default password and belongs to one or more groups:

User Password Groupsguest guest guestattendant attend customer,supervisor superv data, customer,

draft

page 8 of 10

dataextractor dataex data, customer,webmaster master www, customer, configurer config config, customer,manager manage data, config, customer,

www, sysadmin sysadmin customer, www, sys, production produce config, capgo, www, bin,

sys, guru meditate config, capgo, www, root,

bin, daemon, sys, disk

GroupsGroups define a set of capabilities. A user can belong to any number of groups including none:

Group Commentguest guest with minimal rightswww embedded websitedsp dsp associated activitiescustomer customer administrative thingscapgo production and support relateddata logger data accessconfig setup and configurationadm general system administration sys general system relateddaemon daemon relatedbin executables and libraries accessroot do (almost) anything

Other ThingsMemory usagecLog and Lua share a common area of memory. In general there are no set limits to the size of programs, scripts, arrays and buffers. The DAQ Engine is allocated memory at config time and will not encounter any run-time issues. Lua scripts are dynamically allocated memory during run-time and may run out of memory if massive data structures are built.

Power Management

draft

page 9 of 10

Temperature sensorsTC-B Thermocuple type BTC-C Thermocuple type CTC-D Thermocuple type DTC-E Thermocuple type ETC-G Thermocuple type GTC-J Thermocuple type JTC-K Thermocuple type KTC-L Thermocuple type LTC-M Thermocuple type MTC-N Thermocuple type NTC-P Thermocuple type PTC-R Thermocuple type RTC-S Thermocuple type STC-T Thermocuple type TTC-U Thermocuple type UPt385 Platinum RTD alpha = 0.0385Pt392 Platinum RTD alpha = 0.0392Pt100 Platinum RTD alpha = 0.0385, R0 = 100

Cu427 Copper RTD alpha = 0.0427NiFe518 Nickel Iron RTD alpha = 0.0518Ni672 Platinum RTD alpha = 0.0672L100 Thermistor R25 = 100 , material = LL300 Thermistor R25 = 300 , material = L

L1K1 Thermistor R25 = 1.1k , material = L

B2252 Thermistor R25 = 2252 , material = B

B3K Thermistor R25 = 3k , material = BB5K Thermistor R25 = 5k , material = B

B6K Thermistor R25 = 6k , material = B

B10K Thermistor R25 = 10k , material = B1

H10K Thermistor R25 = 10k , material = H

H30K Thermistor R25 = 30k , material = HH100K Thermistor R25 = 100k , material = H

H300K Thermistor R25 = 300k , material = H

H1M Thermistor R25 = 1M , material = H

AD22100 Silicon AD22100AD22103 Silicon AD22103AD590 Silicon AD590AD592 Silicon AD592LM135 Silicon LM135LM235 Silicon LM235LM335 Silicon LM335LM34 Silicon LM34LM35 Silicon LM35LM45 Silicon LM45LM50 Silicon LM50LM60 Silicon LM60MTS102 Silicon MTS102MTS103 Silicon MTS103MTS105 Silicon MTS105S8110 Silicon S8110S8120 Silicon S8120TMP17 Silicon TMP17TMP35 Silicon TMP35TMP36 Silicon TMP36TMP37 Silicon TMP37

ResistanceR GenericRex GenericConductivity Generic

VoltageV Generic voltageHV Generic high voltage (attenuated)ICS1 GenericICS2 Generic

CurrantI Generic currentIm Generic4-20mA Generic 4-20 mA current loop

Iex Generic current, external shunt

BridgeBridge Full bridge, 4, 5 or 6 wire, voltage excitationBridge_I Full bridge, 4, wire, current excitationHalfBridge Half bridge, 3, 4 or 5 wire, voltage excitationHalfBridge_I" Half bridge, 3, wire, current excitationQuarterBridge Quarter bridge, 2, 3 or 4 wire, voltage

excitation

FrequencyFreq Generic frequencyPeriod Generic periodVib_wire Vibrating wire sensor

StateState Generic stateUpCounter Generic up counterDownCounter Generic down counter

NumberV_State GenericV_UpCounter GenericV_DownCounter GenericV_Number GenericTime Generic real time clockEvent Generic time stamp

SpecialsRH_Pt100 Two Pt100sRH_TC_T Two Thermocople type T (one differential)testSensor Special

Smart SensorsSerial Generic RS232, R2485, usbcLog output published by another cLog unitNetwork Generic Ethernet (TBD)ZigBee Generic (TBD)BlueTooth Generic (TBD)RapidIO Generic (TBD)

Internal Engine Sensors EngineTemp Internal SiliconTC_Ref1 Internal Pt100TC_Ref2 Internal Pt100TC_Ref3 Internal Pt100TC_Ref4 Internal Pt100Vbat Internal generic voltageIbat Internal generic currantLongitude Internal GPS longitudeLatitude Internal GPS latitudeAltitude Internal GPS altitudeSpeed Internal GPS speedDirection Internal GPS headingUST Universal time

Notes:Wiring options are defined in the sensor configuration description.

Appendix: Generic and Proprietary Sensors Supported

page 10 of 10

cLog DAQ ConfigurationA Short Reference

Acknowledgments

Lua is a wonderful scripting language. We thank Roberto Ierusalimschy s and the Lua community for for making it possible. I would also like to thank Matthew Percival for his contributions to much of the Capgo s embedded code that has extended Lua to support our very specialized hardware.

Graham HenstridgeCapgo Pty Ltd

draft

DAQ Config LibraryThe DAQ Config library for advanced users only. Normally a GUI configuration wizard or other high level tool would generate and process the configuration tables as described in this reference.The functions should only be used during initialization. In some instances the order of execution of these functions is important due to prior dependencies - see initialize.lua file.

Functionsconfig.calibrate ( calibration_table )

Processes in the calibration_table.config.configData ( conf_data_table )

Processes config_data_table. Returns number of lines processed or nil and error message.

config.debug ( verbosity_level )Sets the system verbosity_level 0 - 10 (default = 3)

config.finish ( )Does linking. Last config function to be called.

config.fundamentals ( fundamental_table )Builds fundamental set from fundamental_table. Returns 1, or nil and error message.

config.fusers ( fuser_table )Builds fuser set from fuser_table. Returns 1, or nil and error message.

config.getRecipeOpList ( [option] )Returns a table array of recipe operations filtered according to the option number:

none Defaults to all recipe operations1 Valid first (source) operations of a recipe 2 Valid subsequent operations3 Valid terminating operations4 All pass-through operations5 All pipe joiner operations6 All recipe operations

Allows host to validate operations in script building.config.modbus ( modbus_table )

Define the modbus register set from the modbus_table. Returns 1,or nil and error message.modbus_table = {

reg_set1_name = { num_of_reg [ v_name_list ] }reg_set2_name = { num_of_reg [ v_name_list ] }etc ... }

wherereg_set_name Name of register set. Use convention:

regxxxx or refFxxxxwhere four digits xxxx refers to starting register number, F indicates a floating point registers (i.e. two 16 bit registers)

num_of_reg Defines the num. of registers allocatedv_name_list List of variable and / or vectors that map

the to modbus registersconfig.parameters ( parameter_table )

Builds the parameter set from the parameter_table. Returns 1,or nil and error message.

config.recipes ( recipe_table )Processes recipes defined in the recipe_table. Returns number of recipes processed, or nil and error message. The recipe_table format is:recipes = {

recipe1_name = { { op = operation1 [, pipe = {size1, len1}] [, config =

config1 | config_table1] }, { op = operation2 .... }, {etc ... }}

The config definition provides additional data that may be required. This can be from a named an entry in the configData table, or explicitly defined table (that is

appended to the configData table with the name “XXXX”.

config.schedules ( schedule_table )Loads the schedule_table. Returns number of schedules processed, or nil and error message.schedule_table = {

schedule1_name = { property1 = value1 [, property2 = value2 [,

property3 = value3 [, ....]]] }schedule2_name = { ....... }etc .. }

Valid properties are:type Schedule type:

time - time triggered (default) event - asynchronous event triggered alarm - alarm triggered

waterfall Name of waterfall to activatetrigger Name of valid trigger sourcepriority priority of schedule (0-9, 0 is highest).offset Offset in seconds from midnightperiod Time between activations in seconds.period_m Time between activations in minutesperiod_h Time between activations in hoursperiod_d Time between activations in daysduration Duration in seconds that schedule

active. If zero, assumes schedule will remain active until stopped.

state One of three states: disable - can not become active. enable - allowed to become active active - currently active

config.sensors ( sensor_table )Loads the sensor_table into the DAQ Engine. Returns number of sensorGroups processed, or nil and error message. Format of sensor_table is:

sensors = {sensor1_name = { property1 = value1 [, property2 = value2 [,

property3 = value3 [, ....]]] },sensor2_name = { ... },etc ... }

Valid properties are:group Group name sensor belongs. Required.type A supported sensor type. excite Excitation requirements. Options are:

voltage - excitation voltage in volts.current- excitation current in amps.frequency - hertz, default = 0.0tolerance - control tolerance

T Time-constant in secondscalib Calibration in terms of deviation from

nominal by y=a+bx. Valid properties:scale scale factor, default = 1.0offset offset, default = 0.0shunt value of shunt resistor on Rref reference value

var2 A general purpose variable ref Name of a data source that can provide

a reference value for some sensor typeswiring Defines the sensor wiring (see below)Returns the number of sensors processed, or nil and an error message.

config.sensorGroups ( sensor_group_table )Loads sensor_group_table. All sensors must belong to a group, even if single sensor. Group properties:model manufacturer s sensor model nameserial manufacture s sensor serial number plant sensors owner s assigned serial number

cLog DAQ Config. Short Reference

page 1 of 6

category the category of sensor - one off: external - standard external sensorinternal - internal sensorext-serial - external smart sensorint-serial - internal smart sensorext-network - external smart

networked sensorint-network - internal smart

networked sensorurl url address if sensor is networkedpower Sensor group s power requirements and

and wiring. Valid sub-properties:chan - the super channel numberneg - terminal for negative power leadpos - terminal for positive power leadV - voltage requirement in voltsI - current draw in amperesT - warm-up time in seconds

teds TEDS and where it is to be found. Sub-properties:class - IEEE Std 1451.4 class ( 1 or 2 )neg - terminal for negative TEDS leadpos - terminal for positive TEDS lead

config.smartSensors ( smart_sensor_table )Loads smart_sensor_table. Returns number of smart sensors processed, or nil and an error message. The format of the smart_sensor_table is:smartSensors = {

sensor1_name = { { property1 = value1 [, property2 = value2 [,

property3 = value3 [, ....]]] },sensor2_name = { ... },etc ...

}Valid properties are:group Group sensor belongs. Required.type Sensor type - see AppendixT Time-constant in secondscalib defines sensors calibration as deviation

from nominal according to y = a +bxValid sub-properties are:scale - scale factor, default = 1.0offset - offset, default = 0.0

initialize defines an initialization string to be sent to the smart sensor after power-up

prompt defines a prompt string to be sent to the smart sensor when data is required.

parse parsing string to extract data from a returned data string. Identical to the scanf() format string in “C”.

wiring TODOconfig.system ( system_table )

Loads system wide properties defined in system_table. Properties are:title Title of this configuration. description Brief description of the configuration.configDir Configuration name.notes Notes about configuration (4kB max). root Path to base directory. Defaults to “/” logPath Path from root for error and progress

logs. Defaults to “var/log/capgo/”.dataPath The path from root to where collected

data archives. Default is “usr/share/capgo/data/”.

scriptPath The path from root to where Lua script files are placed. The default is “usr/bin/capgo/”.

tempPath Path from root to where temporary Lua and plot files are kept. Default is “tmp/”

genPath Path from root to where test signal source files are kept. Default is “usr/share/capgo/gen/”.

maxOpenFiles Maximum number of files allowed to be open at any time.

verbose See the engine.verbose().Default directory structure reflects standard Linux file placement conventions.

config.systemSensors ( system_sensor_table )Loads system_sensor_table. Returns number of system sensors, or nil and error message. The format of the system_sensor_table is:systemSensors = {

{ name1, setup1, scale1, offset1, T1 },{ name2, setup2, scale2, offset2, T2 },etc ... }

where:name Name of measurement pointsetup Hexadecimal of the setup bit pattenscale Scale factoroffset OffsetT Measurement point s time-constant

This table is supplied with the cLog hardware. Don t change without good reason.

config.tags ( tag_table )Define tag set from the passed tag_table. Returns 1, or nil and an error message. Tag_table format:tags = {

tag_name_1 = { property_name = property_value [, property_name = property_value [, ....]] },tag_name_2 = { ... },etc ...

}Valid properties are:param Name of measurement parameter in

parameter table. Required. recipe Name of recipe in recipe table.

Required. fileID Name of the directory in which the

archive data is placed. Required if the recipe has an archive operation.

T Time-constant in seconds - defaults to measurement parameter time-constant.

err Error limits. Defaults to parameter error. Used in compression.

block Sets the preferred data-pipe packet size. Default to a speed related value

capture Defines a set of capture destinations for capture operations in the tag s recipe.

input Input data source name and properties. Required. Expects a table with the source-type assigned a source-name: input = {type = “name”}wherename - a sensor, fuser or tag name.type - any of sensor, sysSensor, smartSensor, tag, variable, vector, fuser, generator, file, modbus, sampleRate

alarms Alarms in the order in which they are defined in recipe. Required if alarms in recipe. Example:alarms = { “wind_100kt”, “wind_110kt” }

config.tagGroups ( tag_groups_table )Define tag group from tag_groups_table. Returns 1, or nil and error message.

A tag_groups_table format:tagGroups = {

group_name1 = { tag_name1 [, tag_name2 [, ... ]] },group_name2 = { ... },etc ... }

config.variables ( variables_table )Defins set of variable from variables_table. Returns 1, or nil and error message. Identical to var.create( ). The

draft

page 2 of 6

variables_table format is a list of named variables, each assigned initial value.

config.vectors ( vectors_table )Defines a set of vectors and their size from the vectors_table. Returns 1, or nil and error message. The vector_table is a table list of vector names, each assigned a size.

config.waterfalls ( waterfalls_table )Defines a waterfall set from the waterfalls_table. Returns 1,or nil and error message.

config.print ( item_name )Prints details item. Valid item_names: calibration, configData,

fundamentals, fusers, modbus, tags, parameters, recipes, schedules, sensors, syst, sensorGroups, smartSensors, systemSensors, tagGroups, variables, vectors, plumbing and all.For debugging and documentation.

config.printFirstWithErrors ( )Prints the items associated with first encountered error.

config.printParticular ( )For debugging.

config.printErrorSummary ( )For debugging.

config.printDiag ( )Prints error diagnostic. Helpful is diagnosing non-syntactical errors in the configuration data file.

Configuration Script FilesIn a standard setup there are four configuration files: - process.lua, initialize.lua, config.lua and calibrate.lua. The default location of the files is ./usr/bin/capgo/.All the configuration files are in standard Lua and are easily modified using any text editor.

draft

page 3 of 6

RecipeA recipe is defined by a series of nested tables: recipes = { recipe_name = { { op = “recipe_op” [, pipe = {size [, len] } ] [, config =

“config_name” | config_table] } ....}where recipe_name Is the name of this recipe. op Operation (see list below)pipe Defines data frame size (num. of samples)

and length len (num. of packets). Defaults sensibly set based on tag s time-constant.

config Configation data required by some recipe ops. Can be ref to main configData or be a table of configData

There is no reasonable limit to the length and number of recipes. The typical recipe is 4 to 6 operations in length, but occasionally could be many more.

configDataSome DAQ Recipe operations require additional configuration data. This is obtained from configData definitions that can provide any number of numbers and 5 text strings.

configData = { name = { [number_list] [, string_list] } ,etc ... }

wherename Name of configData entrynumber_list List of coma separated numbersstring_list List of coma separated strings (5 max)Example:

configData = { alarm1 = { 0.1, 0.2, 0.1, 0, 0, 5, 1, “Over_Temp” }, poly1 = { 0.001, 1.263, 0.001809 } }

DAQ recipe operationsRecipe operations can be categorized in several ways. One useful categorization is by plumbing impact: pipe sourcing, flow-through, pipe joiners and pipe terminators. All recipes must begin with a pipe souring operations, and finish with a pipe terminating operation.

Source OpsDefine the input source to a tag.genericIn

Set source from the tag s input source name property.mainAdc

Set source from the main measurement system. houseAdc

Set source to from the house-keeping system.tagInput

Set source from another tag output.sinWave

Set source from a software sine wave generatorsquareWave

Set source from a software square wave generatordualSinWave

Set source from a dual software sine wave generatorreadFile

Set source from an ascii floating point file, single passreadFileLoop

Set source from a ascii floating point file file, looping.readFileInt

Set source from an ascii integer file, single passreadFileIntLoop

Set source from an ascii integer file, loopingreadFileText

Set source from an ascii text file, single passfuser

Set source to from a fuser variable

Set source to from a variable. Sample rate is equal to the main loop speed.

vectorSet source to a vector, as block data. Sample rate is equal to the main loop speed.

smartSensorSet source to from smart sensor.

modbusSet source to from a modbus register. Sample rate is equal to the main loop speed.

Pass through recipe operations

Scaling and LinearizingscaleAdc

Scale raw adc data to SI units of volts, amperes, hertz or counts according to tag s sensor type.

linearizeLinearize scaled data to engineering units according to tag s sensor type.

polynomialApply a polynomial to the data

Repairing DatarepairNaNs

Endeavors to “fix” nan s by interpolation.repairFars

Replace far points by interpolated values

Constrainclip

Clips the data to range defined in configData:C[1] Lower limit.C[2] Upper limit

gatePasses or discards data stream at frame level based on the value of a variable defined in configData text.

variable > 0.0 pass datavariable <= 0.0 discard data

turningPointDiscards all sample points not peaks or troughs. Can operate on integer or floating point data

Windowing DataWindows created dynamically, with last four retained to reduce re-creation. Window defined by type and input pipe size.window_trapezoidal

Applies a trapezoidal window.window_bartlett

Applies a Bartlett (or Triangle) window.window_hanning

Applies a Hanning window.window_blackman

Applies a Blackman window.window_blackmanExact

Applies a Harris-Blackman window.window_harrisBlackman

Applies a Harris-Blackman window. window_flatTop

Applies a Flat To window. window_blackmanOptimal

Applies a Blackman Optimal window. window_welsh

Applies a Welsh window.

MathsFor math ops with variable or vector, define name in configDatacal.invert

Inverts (i.e. 1/x) each member of data frame.cal.square

Squares (i.e. x2) each member of data frame.cal.squareRoot

Square root (i.e. x0.5) of each member of data frame.cal.absolute

Absolute value (i.e. |x|) of each member of data frame.cal.log10

Log base ten of each member of data frame.

DAQ Recipes and Configuration Data

page 4 of 6

cal.10log1010 times log base ten of each member of data frame.

cal.20log1020 times log base ten of each member of data frame.

cal.expandInverts (i.e. 1/x) each member of data frame.

cal.addVariableAdds a variable each element of data frame.

cal.subtractVariableSubracts a variable each element of data frame.

cal.multiplyVariableMultiply each element of data frame by a variable.

cal.divideVariableDivide each element of data frame by a variable.

cal.addVectorAdds a variable each element of data frame.

cal.subtractVectorSubracts a variable each element of data frame.

cal.multiplyVectorMultiply each element of data frame by a variable.

cal.divideVectorDivide each element of data frame by a variable.

Transformationspectra.null

Place holderspectra.FFT

Applies a real discrete Fast Fourier Transform, resulting in an amplitude spectra.

spectra.pwFFTApplies a real discrete Fast Fourier Transform to input, resulting in power spectra.

spectra.logPwFFTApplies a real discrete Fast Fourier Transform to input, resulting in a log10 power spectra.

spectra.cepstrum Applies a real discrete Fast Fourier Transform to produce power spectra. A log10 is applied then another FFT is applied to produce the “cepstrum”.

spectra.goertzelApplies a Goertzel transformation at the frequencies listed in named vector, and returns the coefficients of the transformation in table-array of the same size as the named vector.

Controlpid

proportional, Integral, derivative control algorithm with coefficients defined in configData

C[1] Proportion gainC[2] Integral gainC[3] Differential gainC[4] Time constant in secondsC[5] Acceleration feed forwardC[6] Friction feed forwardC[7] Velocity feed forwardC[8] Min outputC[9] Max outputC[10] Max slew rateC[11] Biastext Set point variable name

The units are those of the parameter being controlled

Accumulating OperationsAccumulation absorb data for a period of time, process it in some way. The accumulated results are released when the total number of samples processed exceeds the shedding value in the configData, or when the tag.accumulate() command is issued.histogram

Function builds a histogram based on a definition in a configData entry:

C[1] N, total bins incl. <min, >max, nan & total.C[2] Number of samples before sheddingC[3] Minimum threshold

C[4] Maximum thresholdThe results accumulated in output pipe s load frame in following order:

bin(1) < minimum threshold countbin(2) > minimum threshold but less than next ...bin(N-3) < maximum threshold but more than

previous thresholdbin(N-2) > maximum threshold countbin(N-1) not a number countbin(N) total number of samples processed

(= sum of all other bins)density

Realtime kernel density estimate based on properties defined in a configData entry:

C[1] Minimum threshold in the parameter s units.C[2] Maximum threshold in the parameter s units.C[3] Smoothing parameter, typically in range 1 to

100, with 10 a good starting point.C[4] N, total number of bins can be any

reasonable number, only limited by memory.C[5] Number of samples to be processed before

shedding output dataFrame. C[5] = 0prevents automatic shedding.

rainflowRainflow or cycle counting, with properties defined in configData:

C[1] Peak buffer size in number of samplesC[2] N, the number of cycle binsC[3] M, the number of mean binsC[4] Minimum cycle threshold in tag unitsC[5] Maximum cycle thresholdC[6] Minimum mean thresholdC[7] Maximum mean thresholdC[8] Number of samples before shedding data

Maps the output into a new data-pipe with the following arrangement:

1, 2, 3, ... N N+1, N+2, N+3, ... 2N2N+1, 2N+2, 2N+3, ... 3N ... ... ... ... ...

(M-1)N+1, (M-1)N+2, (M-1)N+3, ... M.Nwhere N is the number of cycle bins and M the number of mean bins.

CountersThe counter recipe operations provide for fast software (up to 20 kHz) 31 bit counting. The configData definition for all counter operations is:

C[1] threshold in tag s measurement unitsC[2] hysteresis also in the tag s unitsC[3] negative going de-bounce period in samplesC[4] positive going de-bounce period in samplesC[5] counting edge: 0 = neg, 1 = pos, 2 = bothC[6] reload value, (defaults to full scale)C[7] count before releasing count for processing“variable_name” = optional name of variable into which

the progressive count is placedcount_up

A simple incrementing counter. On reaching its reload value, it rolls over to zero.

count_downA simple decrementing counter. On reaching zero it is loaded with the reload value.

DecimationDecimation is the process of reducing the volume of a data stream in ways that endeavor not to reduce the useful information content of the data.. turningPoint

Discards all sample points that are not peaks or valleys. Sample timing is lost.

draft

page 5 of 6

decimateThis operation does a simple N:1 decimation by taking the average of N samples and passing the result to a new pipe. N = C[1] in configData.

FilteringBi-quad filter where the properties are from configData:

C[1] gain of filter in dBC[2] center frequency in hertzC[3] default sampling rate in hertzC[4] bandwidth in octaves

The filters can be cascadedfilter_lowpass

Apply a low pass bi-quad filter.filter_highpass

Apply a high pass bi-quad filter.filter_bandpass

Apply a band pass bi-quad filter.filter_notch

Apply a notch bi-quad filter.filter_peaking

Apply a peaking bi-quad filter.filter_lowshelf

Apply a low shelf bi-quad filter.filter_highshelf

Apply a high shelf bi-quad filter.Note: A filters working coefficients are recalculated when a tag s sample rates changes.

AlarmsAlarms provide for upper and lower threshold testing, hysteresis and response time controlalarm

Alarm properties are defined in a configData entry:C[1] Low threshold in tag measurement unitsC[2] High threshold in tag measurement unitsC[3] Hysteresis in tag measurement unitsC[4] Response time in secondsC[5] Response time in samplesC[6] Priority (0 to 9, 0 is highest)C[7] Enable state ( 0 = disabled, 1 = enabled )“alarm_name” = unique alarm identifier text

Multiple alarm operations may be cascaded.

CaptureTake a “snap-shot” of a tag s data stream. Destination for captured data defined in configData string, (only useful if these is one recipe per tag), or defined in a tag s capture property. If more that one capture operation is included in a recipe, then the a destination for each should be listed and they are assigned in order of occurrence.capture_to_variable

Last value of the current data packet into the nominated variable.

capture_to_vectorCurrent data packet into the nominated vector.

capture_ave_to_variableAverage (arithmetic mean) of the current data packet into the nominated variable

capture_to_doutLast value of the current data packet into the nominated digital output.

capture_to_aoutLast value of the current data packet into the nominated analog output.

capture_to_modbusLast value of the current data packet into the nominated modbus register.

Terminating a RecipeAll recipes need to be properly terminated. Loads latest value and close off the data-pipe for recycling.terminate

Terminate recipe that does not require logging.

archiveProgressively logs data. The archive operation can optionally be provided with customization via a configData entry:

C[1] Buffer size in compressed points: 0 = sets buffer to default size, usually 256 n = sets to n kB or if over the maximum allowed, to the maximum.

C[2] Compression mode: 0 = default (first order trend compression) 1 = no compression, 2 = first order trend compression 3 = compression for non time-series data

C[3] Number of log files concatenated to produce an archive file: 0 = default of ten (default) n = n files, or if n > 100, sets to 100.

C[4] Number of archive files per archive directory: 0 = default of 25. n = n files, or if n > 100, sets to 100.

C[5] Maximum total number of archive filesmax and default = 99 * number of archive files per archive directory

C[6] Archive file compression mode 0 = no compression (default) 1 = bzip2 compression level (1 = fastest, 9 = best)

“stop” Text that indicates stop archiving when the archive is full

The absence of a configData reference ensures properties are set to defaults.

draft

page 6 of 6