Hubo Library

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Typedefs | Functions
Timing and monitoring support

## Typedefs
typedef void(* | HuboLib::T_pfn_CycleTickCallback) (unsigned long *pADChannelValues, unsigned char *pDigitalInputValues, unsigned char *pDigitalOutputValues)
| Prototype definition of the callback function beeing called an every cycle time tick. More...
typedef void(* | HuboLib::T_pfn_ChannelDelayCallback) (__int64 cycleCount, __int64 t_Overrun_ms)
| Prototype definition of the callback function beeing called when the cycle time slice has been violated. More...

## Functions
bool | HuboLib::Set_Cycle_Time (long cycleTime)
| Sets the backgrounds threads polling interval in ms. More...
bool | HuboLib::Register_CycleTickCallback (T_pfn_CycleTickCallback pFnCycleTickCallback)
| Registers a callback function called on every cycle tick. More...
bool | HuboLib::Unregister_CycleTickCallback (T_pfn_CycleTickCallback pFnCycleTickCallback)
| Unregister a callback previouly registered by a call to Register_CycleTickCallback(). More...
bool | HuboLib::Register_ChannelDelayCallback (T_pfn_ChannelDelayCallback pFnChannelDelayCallback)
| Register a callback to be called whenever the cycle time has been violated by more than one cycle time. More...
bool | HuboLib::Unregister_ChannelDelayCallback (T_pfn_ChannelDelayCallback pFnChannelDelayCallback)
| Unregister a callback previouly registered by a call to Register_ChannelDelayCallback(). More...

## Detailed Description

## Typedef Documentation

typedef void(* HuboLib::T_pfn_ChannelDelayCallback) (__int64 cycleCount, __int64 t_Overrun_ms)

Prototype definition of the callback function beeing called when the cycle time slice has been violated.

Registering a callback routine provides a way to an application to get notified whenever the background thread was not able to finish its work in the cycle time as being defined. This is might be required for applications the require a precise timing e.g. a controller calculating new set points from sample deviation and time. Just like the cycle tick callback this function is also called by the background thread - thus all timing considerations also apply to this callback function. The channel delay callback is being called as the last callback function within one time slice.

Parameters

  cycleCount | The number of the cycle currently being executed.
  t_Overrun_ms | Time in ms the cycle time is violated. Note that this value is at least as big as the cycle time itself, otherwise the callback would not be called.
  pDigitalOutputValues | Pointer to the buffer of the digital output values.

See also
  Register_ChannelDelayCallback(), Unregister_ChannelDelayCallback(), Register_CycleTickCallback(), Set_Cycle_Time(), Set_MCP3x08_Oversampling()
  For an example on how to register and use the channel delay callback function refer to the demo SampleCallbacks.cpp.

Note
  Be aware of that the callback routine will be executed within the background thread!

Definition at line 95 of file hubolib.h.

typedef void(* HuboLib::T_pfn_CycleTickCallback) (unsigned long *pADChannelValues, unsigned char *pDigitalInputValues, unsigned char *pDigitalOutputValues)

Prototype definition of the callback function beeing called an every cycle time tick.

Once registered the background thread will call this function right after latching input from the digital and analog inputs and propagating changes to the digital outputs. Since the calling frequency is determined by the call to Set_Cycle_Time() care needs to be taken that the operations performed do not exceed the time slice of one cycle tick.
It also needs to be considered that the background thread runs at the maximum priority possible hence the entire rest of the application will be blocked during the execution of the callback. While the callback is executed the background thread still owns the internal mutex protecting IO buffers from access. So an application (regardless to its threads scheduling policy and priority) calling into the library will be blocked until the callback returns. This is to ensure that - if a cycle time should be violated - the library get as many CPU time granted in order to catch up with cycle ticks that are delayed.

Parameters

  pADChannelValues | Pointer to the buffer of the analog input values.
  pDigitalInputValues | Pointer to the buffer of the digital input values.
  pDigitalOutputValues | Pointer to the buffer of the digital output values.

See also
  Register_CycleTickCallback(), Unregister_CycleTickCallback(), Set_Cycle_Time(), Register_ChannelDelayCallback(), Set_MCP3x08_Oversampling()
  For an example on how to register and use the cycle tick callback function refer to the demo SampleCallbacks.cpp.

Note
  Be aware of that the callback routine will be executed within the background thread!

Definition at line 73 of file hubolib.h.

## Function Documentation

bool HuboLib::Register_ChannelDelayCallback | ( | T_pfn_ChannelDelayCallback | pFnChannelDelayCallback | ) |

Register a callback to be called whenever the cycle time has been violated by more than one cycle time.

This function is used to register a callback routine that is called whenever the cycle time is delayed for at least the time of one cycle time. The callback routine receives information on the number of the cycle as well as the absolute delay in ms.
Unregistration is performed by calling Unregister_ChannelDelayCallback().

Parameters

  pFnChannelDelayCallback | Pointer to the callback function to be called whenever the cycle time is violated by more then 1 cycle tick. Function pointers are not chained. Passing 0 as an argument disables the callback.

Returns
  The function returns true if the new callback could be registered. If the maximum number of callback functions has been reached the function returns false.

See also
  Unregister_ChannelDelayCallback(), Register_CycleTickCallback(), Set_MCP3x08_Oversampling()
  For an example on how to use Register_ChannelDelayCallback() refer to the demo SampleCallbacks.cpp.

Note
  Be aware of that the callback routine will be executed within the background thread! In order to avoid dead lock situations callback routines must not call any of the functions as exposed by the hubolib.h interface (unless otherwise stated e.g. for xxx_Raw()-routines)!
  Also be aware of that frequently breaking the cycle time indicates that the background worker thread is overloaded. Since this thread is owning the mutex for accessing the data (which indirectly is also being used by other library functions) - calls into the library will be blocked for the time the cycle time is broken. This is even true for a call to Register_CycleTickCallback(0) or any other callback that has been registered) which potentially could even "solve" the situation by removing the cause of the cycle time to break.
  If you experience you application to not properly terminate then check for the cycle time to not be broken (e.g. for debugging purposes register a callback routine that asserts when the cycle time gets broken).
  See the comments within the code of SampleCallbacks.cpp for more information on this problem.

bool HuboLib::Register_CycleTickCallback | ( | T_pfn_CycleTickCallback | pFnCycleTickCallback | ) |

Registers a callback function called on every cycle tick.

This function is used to register a callback routine that is called on each cycle tick after the input of the hardware has been latched and new output values have been written. Registering such a callback is useful when acurate timing is essential to e.g. a controller algorithm requiring to get called equidistant in time. The callback routine will have access to the internal buffers of the IO area.
Unregistration is performed by calling Unregister_ChannelDelayCallback().

Parameters

  pFnCycleTickCallback | Pointer to the callback function to be called on each cycle tick. Function pointers are not chained. Passing 0 as an argument disables the callback.

Returns
  The function returns true if the new callback could be registered. If the maximum number of callback functions has been reached the function returns false.

See also
  Unregister_CycleTickCallback(), Register_ChannelDelayCallback(), Set_MCP3x08_Oversampling()
  For an example on how to use Register_CycleTickCallback() refer to the demo SampleCallbacks.cpp.

Note
  Be aware of that the callback routine will be executed within the background thread! In order to avoid dead lock situations callback routines must not call any of the functions as exposed by the hubolib.h interface (unless otherwise stated e.g. for xxx_Raw()-routines)!

bool HuboLib::Set_Cycle_Time | ( | long | cycleTime | ) |

Sets the backgrounds threads polling interval in ms.

When reading or writing digital values to the IO expander or rading analog values from the ADC these operations are not performed on the real hardware. Instead calls to Get_DO_Channels(), Set_DO_Channels(), Get_AI_Channel() etc. are accessing internal buffers that contain the values latched or to be written by the background thread. The speed at which these buffers are latched or transmitted to the hardware is determined by the so called cycle time. While the background thread runs at the highest priority possible other threads usually would not break the cycle time slice. There are however, limitations for setting the time slice. Setting it to 1ms will heavily stress the OS scheduler and therefore is not recommended. Also the number of analog channels latched and oversampled as specified by a call to Set_MCP3x08_Oversampling() will heavily impact the CPU time consumed in one cycle tick. Therefore a call to Set_Cycle_Time() will perform a brief check on plausibility prior to accepting a new cycle time.
The default for the cycle time upon initializing the library is 10ms thus resulting in a cycle tick of 100Hz.
Note that a change to the cycle time value will first take effect after the background thread has finished the current cycle tick.

Parameters

  cycleTime | Defines the cycle time of the background thread in ms.

Returns
  For a plausible cycle time the function returns true, false otherwise.

See also
  Register_CycleTickCallback(), Unregister_CycleTickCallback(), Register_ChannelDelayCallback(), Set_MCP3x08_Oversampling()
  For an example on how to use Set_Cycle_Time() refer to the demo SetCycleTime.cpp.

bool HuboLib::Unregister_ChannelDelayCallback | ( | T_pfn_ChannelDelayCallback | pFnChannelDelayCallback | ) |

Unregister a callback previouly registered by a call to Register_ChannelDelayCallback().

This function is used to unregister a single callback routine previously added. If pFnChannelDelayCallback is 0 then the call will unregister all callback routines.

Parameters

  pFnChannelDelayCallback | Pointer to the callback to be unregistered from the list of callback functions or 0 if all callback functions are to be removed from the list.

Returns
  The function returns true if the callback could be found and unregistered.

See also
  Register_ChannelDelayCallback()
  For an example on how to use Unregister_ChannelDelayCallback() refer to the demo SampleCallbacks.cpp.

bool HuboLib::Unregister_CycleTickCallback | ( | T_pfn_CycleTickCallback | pFnCycleTickCallback | ) |

Unregister a callback previouly registered by a call to Register_CycleTickCallback().

This function is used to unregister a single callback routine previously added. If pFnCycleTickCallback is 0 then the call will unregister all callback routines.

Parameters

  pFnCycleTickCallback | Pointer to the callback to be unregistered from the list of callback functions or 0 if all callback functions are to be removed from the list.

Returns
  The function returns true if the callback could be found and unregistered.

See also
  Register_CycleTickCallback()
  For an example on how to use Unregister_CycleTickCallback() refer to the demo SampleCallbacks.cpp.