SetGlobalTimer()

Description

Sets the parameters of a global timer.

  • Unlike state timers, global timers can be triggered from any state (as an output action), and handled from any state (by causing a state change). Any subset of global timers can be triggered or canceled from any state.

  • An optional onset latency can be configured, following the timer trigger

  • Following the onset latency, a "start" event is generated, and can trigger a state change.

  • Then, following the timer duration, an "end" event is generated, which can also trigger a state change.

  • A digital or PWM (LED) output channel can be linked to the timer.

    • The linked channel is set "high" when the timer starts, and "low" when it ends. PWM values may be specified for onset/offset.

  • Separate serial output messages can be linked to the timer start and end events to control modules.

  • Global timers can be set to 'Loop'; repeat until they are explicitly canceled, or until a fixed number of iterations.

    • Each loop iteration generates a start and stop event (this can be disabled for high-frequency loops)

    • A configurable interval separates loop iterations (default = 0 seconds)

  • Global timers can be linked to trigger other global timers. Following the timer's onset delay, any linked timers will be triggered.

  • The number of available global timers is a configurable parameter specified in the state machine firmware.

Syntax

The function uses argument-value pairs. These must be listed in order (for efficiency), up to the last argument you need. Beyond that, optional arguments (denoted by [ ]) may be omitted):

NewStateMachine = SetGlobalTimer(StateMachineStruct, 'TimerID', TimerNumber,...

'Duration', TimerDuration, ['OnsetDelay', OnsetDelay],...

['Channel', OutputChannel], ['OnsetValue', OnsetValue],...

['OffsetValue', OffsetValue], ['Loop', LoopMode],...

['GlobalTimerEvents', EventsEnabled], ['LoopInterval', LoopInterval],...

['OnsetTrigger', OnsetTriggerByte)

where [ ] = optional argument

Parameters

  • StateMachineStruct: The state machine description whose global timer you are setting (typically named 'sma').

  • TimerNumber: The number of the timer you are setting (an integer, 1-5).

  • TimerDuration: The duration of the timer, following timer start (0-3600 seconds)

  • OnsetDelay: A fixed interval following timer trigger, before the timer start event (default = 0 seconds)

    • If set to 0, the timer starts immediately on trigger and no separate start event is generated.

  • OutputChannel: A string specifying an output channel to link to the timer (default = none)

    • Valid output channels can be viewed from the "inspect" icon on the Bpod Console.

  • OnsetValue: The value to write to the output channel on timer start (default = none)

    • If the linked output channel is a digital output (BNC, Wire), set to 1 = High; 5V or 0 = Low, 0V

    • If the linked output channel is a pulse width modulated line (port LED), set between 0-255.

    • If the linked output channel is a serial module, OnsetValue specifies a byte message to send on timer start.

  • OffsetValue: The value to write to the output channel on timer end (default = none)

  • LoopMode: 0 = off (default). If set to 1, global timer loops until canceled or until trial end. If >1, indicates a fixed number of loop iterations to execute (up to 255).

  • EventsEnabled: 1 = on (default). If set to 0, timer onset and offset events are not generated. Disabling events is useful for cases where the global timer is rapidly cycling to control a stimulus, and would otherwise generate a huge number of ignored behavior events.

  • LoopInterval: A configurable delay between the end of a timer loop and the beginning of the next one (default = 0 seconds)

  • OnsetTrigger: A byte whose bits indicate other global timers to trigger when the timer starts (following its onset delay).

    • Instead of an integer, the assembler will recognize a character string of 1s and 0s (i.e. '101001' to trigger timers 1,4 and 6)

Returns

  • A state machine struct, updated with the new global timer settings.

Examples

%1. This code generates a state machine that sets a global timer for 3 seconds, triggers it in the first state, and handles it in the second and third states.

sma = NewStateMachine();

sma = SetGlobalTimer(sma, 'TimerID', 1, 'Duration', 3);

sma = AddState(sma, 'Name', 'State1', ...

'Timer', 0,...

'StateChangeConditions', {'Tup', 'State2'},...

'OutputActions', {'GlobalTimerTrig', 1});

sma = AddState(sma, 'Name', 'State2', ...

'Timer', 0,...

'StateChangeConditions', {'Port1In', 'State3', 'GlobalTimer1_End', 'exit'},...

'OutputActions', {});

sma = AddState(sma, 'Name', 'State3', ...

'Timer', 0,...

'StateChangeConditions', {'Port1Out', 'State2', 'GlobalTimer1_End', 'exit'},...

'OutputActions', {});


%2. This code generates a state machine that sets global timer#2 for 2 seconds with a 1.5 second onset delay. The timer is linked to a BNC channel. The timer is triggered in the first state, and handled it in the second and third states.

sma = NewStateMachine;

sma = SetGlobalTimer(sma, 'TimerID', 2, 'Duration', 2, 'OnsetDelay', 1.5, 'Channel', 'BNC2');

sma = AddState(sma, 'Name', 'TimerTrig', ...

'Timer', 0,...

'StateChangeConditions', {'Tup', 'Port1Lit'},...

'OutputActions', {'GlobalTimerTrig', 1});

sma = AddState(sma, 'Name', 'Port1Lit', ...

'Timer', .25,...

'StateChangeConditions', {'Tup', 'Port3Lit', 'GlobalTimer1_End', 'exit'},...

'OutputActions', {'PWM1', 255});

sma = AddState(sma, 'Name', 'Port3Lit', ...

'Timer', .25,...

'StateChangeConditions', {'Tup', 'Port1Lit', 'GlobalTimer1_End', 'exit'},...

'OutputActions', {'PWM3', 255});