|
Hubo Library
|
|
Hubo Library
|
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... | |
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.
| 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. |
| 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.
| 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. |
| 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().
| 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. |
| 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().
| 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. |
| 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.
| cycleTime | Defines the cycle time of the background thread in ms. |
| 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.
| 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. |
| 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.
| 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. |
1.8.8
