====== Free Signals API ==

This is the Free Signals API for PLC specific tasks. It extends the [[http://www.lua.org/manual/5.1/index.html#index|Lua base library]].

===== Digital Inputs ==
==== plc.DI(connector_index, input_index) ==

Returns handle to a digital input. ''connector_index'' is the numeric ID of the IO connector (Currently only Modbus couplers are supported). ''input_index'' is the numeric ID of the digital input on the coupler.

Example:
<code lua>
my_button = plc.DI(0,0)
</code>

==== di:val() ==

Returns the current state of the digital input as a boolean value.

==== di:tostring() ==

Returns a string representation of the digital input with its address and the current state.

==== di:on_rise(callback) ==

Pass a function to be called when the input switches from low to high.

Example:
<code lua>
my_button:on_rise(
   function() print("my_button pressed") end
)
</code>

==== di:on_fall(callback) ==

Pass a function to be called when the input switches from high to low.

Example:
<code lua>
my_button:on_fall(
   function() print("my_button released") end
)
</code>

==== di:on_toggle(callback) ==

Pass a function to be called when the input changes its state from low to high or from high to low.

Example:
<code lua>
my_button:on_rise(
   function(self) print("my_button changed: "..self.tostring()) end
)
</code>

===== Analog Inputs ==
==== plc.AI(connector_index, input_index) ==

Returns handle to an analog input. ''connector_index'' is the numeric ID of the IO connector (Currently only Modbus couplers are supported). ''input_index'' is the numeric ID of the analog input on the coupler.

Example:
<code lua>
my_ai = plc.AI(0,0)
</code>

==== ai:val() ==

Returns the current value of the analog input as a [[http://www.lua.org/manual/5.1/manual.html#2.2|Lua number]].

The value is passed "as is" from the bus coupler. No conversion takes place.

==== ai:tostring() ==

Returns a string representation of the analog input with its address and the current value.

==== ai:on_change(callback) ==

Pass a function to be called when the input changes its value.

Example:
<code lua>
my_ai:on_change(
   function(self) print("my_ai changed: "..self.tostring()) end
)
</code>

Note that it is possible to set a threshold for what is recognized as a value change in the variable ''ai_tresh'' in the config file of each IO connector.

===== Digital Outputs ==
==== plc.DO(connector_index, output_index) ==

Returns handle to a digital output. ''connector_index'' is the numeric ID of the IO connector (Currently only Modbus couplers are supported). ''output_index'' is the numeric ID of the digital output on the coupler.

Example:
<code lua>
my_lamp = plc.DO(0,0)
</code>

==== do:val() ==

Returns the current state of the digital output as a boolean value.

==== do:tostring() ==

Returns a string representation of the digital output with its address and the current state.

==== do:set(value) ==

Sets the digital output to the passed ''value'' converted to a boolean.

You can pass anything as value. Converion to boolean takes place according to the [[http://www.lua.org/manual/5.1/manual.html#2.2|Lua rules]]: Both nil and false make a condition false; any other value makes it true.

==== do:toggle() ==

Inverts the digital output.

===== Analog Outputs ==
==== plc.AO(connector_index, output_index) ==

Returns handle to a analog output. ''connector_index'' is the numeric ID of the IO connector (Currently only Modbus couplers are supported). ''output_index'' is the numeric ID of the analog output on the coupler.

Example:
<code lua>
my_ao = plc.AO(0,0)
</code>

==== ao:val() ==

Returns the current value of the analog output as a [[http://www.lua.org/manual/5.1/manual.html#2.2|Lua number]].

==== ao:tostring() ==

Returns a string representation of the analog output with its address and the current state.

==== ao:set(value) ==

Sets the analog output to the passed ''value'', a [[http://www.lua.org/manual/5.1/manual.html#2.2|Lua number]].

The value is passed "as is" to the bus coupler. No conversion takes place.

===== Timer ==

<note important>Timer API is may be extended if it becomes apparent that more than one timer instance is necessary.</note>

==== plc.timer_init(callback) ==

Initializes the timer. ''callback'' is the function to be called when the timer expires.

This Example prepares the timer to print something periodically. Note hat it is necessary to call ''plc.timer_settime()'' after ''plc.timer_init()'':

<code lua>
plc.timer_init(
   function() print("Timer tick") end
)
</code>

==== plc.timer_settime(secs, usecs) ==

Starts (arms) or stops (disarms) the timer. The timer must be initialized at least once with ''plc.timer_init()'' before.

''secs'' and ''usecs'' is the interval time in seconds and microseconds, just like the [[glibc>Elapsed-Time|struct timeval]] of C.

Passing 0 s and 0 µs stops the timer.

The Example start the timer, wich expires every 500 ms:
<code lua>
plc.timer_settime(0, 500000)
</code>