Time functions

Time functions are functions which produce a value which varies over time, either continuously or discretely.

Implementational note: because Synth is event-driven, a time function may be asked for its state at any arbitrary moment in time. This makes implementation of some functions ‘interesting’.

count

Generates a monotonically rising count at defined intervals.

Arguments:

{
    "interval" : the time between counts
    "modulo" : (optional) the point at which to wrap - if unspecified, never wraps
}

events

Generates an event randomly.

Arguments:

{
    "value" : the value of the event (i.e. what the property gets set to when the event happens)
    "interval" : the average period of the event (ISO8601 e.g. PT3h). Varies randomly around that.
}

mix

Combine timefunctions according to some operator.

Arguments:

{
    "timefunctions" : [] an array of timefunctions
    "operator" : How to combine the timefunctions ("and", "add" and "mul" currently supported)
}

propertydriven

Creates a value between 0 and 1 which is random but derived from a device property and unchanging over time. So the value doesn’t change is the property value doesn’t change. E.g. this can be used to give each device a random cellular signal strength which is different for each device, but constant for that device. E.g. if the property is e.g. an enumerated type, such as hardware version, then the value will be the same for all devices that share the same hardware version.

Arguments:

{
    "property_name" : the name of the property to use as a random seed [defaults to $id]
}

randomwave

Generates a random value between 0 and 1, of programmable period.

Arguments:

{
    "period" : the period with which the random value is updated e.g. "PT1H"
    "lower" : (optional) numbers will be returned within range (lower,upper) - if not specified then range is (0.0, 1.0]
    "upper" : (optional)
    "precision" : (optional) 1 for integer, 10 for 1 decimal point, 100 for 2 decimals etc.
}

sinewave

Generates a sinusoidal wave of programmable period. 32 points are generated per cycle.

Arguments:

{
    "period" : the period of the cycle e.g. "PT10M"
    (the above can be an array, in which case multiple sinewaves are generated and added. This can be useful for Fourier synthesis, modelling events which change on different timescale
     such as wind speeds. By mixing a sufficient number of waves, an effectively random signal can be generated, but one whose value can be calculated for any moment in time
     (unlike standard LFSR randomness generators which are iterative))
    "amplitude" : likewise
    "overall_amplitude" : (optional) scales the overall output
    "overall_offset" : (optional) sets the overall level of the output
    "sample_period" : (optional) if not specified, sinewave(s) are generated at a period which automatically ensures high-resolution.
                        But that might be more than you want, so you can force the period of generation
    "randomise_phase_by" : "$id" (optional) if specified, hashes the value of the named property to offset the phase by an effectively random amount (so multiple devices are all at different points in the cycle)
    "precision" : (optional) If specified, the precision of the output (1= integer, 10 = decimal place, 100 = two decimals)
}