VisionBox Interface Library  1.7.5.0 (2021-12-10)
VIB::Service Class Reference
+ Inheritance diagram for VIB::Service:

Detailed Description

This class contains functions associated with the hardware component (serial number, system temperature, watchdog, firmware updates).

The behavior of this class is different in comparison to other device classes, because it can be opened more than once the same time. Note that the library functions are thread safe but not process safe.

The following table lists the supported features for different hardware entities:

Platform Hardware entity
(see eHardwareType)
eSystemType Supported features
Serial Number[1] Temperature Status Fan Status and Control Watchdog Firmware Update
VisionBox AGE-X1 Mainboard SYST_BASEBOARD AGEXyymm0xxxxx yes yes (control) yes yes
VisionBox AGE-X2 Mainboard SYST_BASEBOARD AGEXyymm1xxxxx yes no yes yes
Smart NIC SYST_NETWORK NIC0yymmxxxxxx no no no yes
Camera Link SYST_CL CL00yymmxxxxxx no no no yes
VisionBox AGE-X3 I/O board SYST_BASEBOARD AGEXyymm2xxxxx no no yes yes
VisionBox AGE-X4[2] Mainboard SYST_BASEBOARD AGEXyymm3xxxxx yes yes (status) yes no
VisionBox AGE-X5 Mainboard SYST_BASEBOARD AGEXyymm4xxxxx no no yes yes
Smart NIC SYST_NETWORK no no no no yes
Camera Link SYST_CL no no no no yes
VisionBox LE MANS[2] Mainboard SYST_BASEBOARD LMNSyymmxxxxxx yes no yes yes
VisionBox DAYTONA Mainboard SYST_BASEBOARD DTNAyymmxxxxxx yes no yes no
VisionBoards Machine Vision Controller SYST_INTERNAL_PCI MVC0yymmxxxxxx no no no yes
PCIe Smart NIC board SYST_NETWORK NIC1yymmxxxxxx no no no yes
PCIe Camera Link board SYST_CL CL01yymmxxxxxx no no no yes
VisionCam XM Mainboard SYST_BASEBOARD VCXMyymmxxxxxx yes no yes no
VisionSensor PV / PV2 Mainboard SYST_BASEBOARD VSPVyymm0xxxxx yes no no no
VisionSensor PV3 Mainboard SYST_BASEBOARD VSPVyymm1xxxxx yes no no no
Machine Vision Manager Mainboard SYST_EXTERNAL_USB MVM0yymmxxxxxx no no yes[3] yes

  1. Serial number format:
    yymm: place holder for production year and month
    xxx...: place holder for a serial number
  2. The VisionBox AGE-X4 and the VisionBox LE MANS can also use the VisionBoards.
  3. Machine Vision Manager: requires firmware ≥ 1.0.0.69 and only SERVICE_WDT_RESET_TYPE_MULTIPLEXER is supported.

Serial Number

The function GetSerialNumber() returns the serial number for the associated hardware component.

The serial number consists of a null-terminated string. The string format is listed in the table above for the different hardware entities.

+ Example code
VIB::VIBSystem *pVIBSystem = NULL;
VIB::Service *pService = NULL;
// create a factory instance for the mainboard
pVIBSystem->OpenDevice(VIB::DT_SERVICE, 0, (VIB::iDevice**)(&pService));
// read the serial number
char serialnumber[32];
pService->GetSerialNumber(serialnumber);
printf("Serial number: '%s'\n", serialnumber);
// Close the device and the factory
pVIBSystem->CloseDevice(pService);
VIB::VIBSystem::DeleteInstance(pVIBSystem);
Please note that error checking was removed to keep the code simple.

Temperature Status

The temperature of the mainboard can be read with GetSystemTemperature().

+ Example code
VIB::Service service;
float temperature;
service.Open();
service.GetSystemTemperature(temperature);
printf("Temperature: %.1f °C\n", temperature);
Please note that error checking was removed to keep the code simple.

Fan Status and Control

Depending on the hardware configuration, the VisionBox AGE-X1 and AGE-X4 can have one or more fans installed.

The VisionBox AGE-X4 supports reading the number of fan channels with GetFanNumberOfChannels() and reading the fan speed with GetFanSpeed().

The VisionBox AGE-X1 supports adjustment of the target temperature for the fan regulation circuit by SetFanTargetTemperature().

Watchdog

The Watchdog can be used to reset the system if the function WatchdogService() is not called within a time period specified by WatchdogSetup().

+ Example code
VIB::Service service;
// create a factory instance for the mainboard
service.Open(0);
// enable Watchdog with a timeout of 3 seconds
service.WatchdogSetup(true, 3000);
// reset Watchdog timer in the main loop
while (progIsRunning)
{
service.WatchdogService();
// do something else
}
// disable the Watchdog
service.WatchdogSetup(false, 3000);
Please note that error checking was removed to keep the code simple.

Starting with firmware version ≥ 1.0.0.37, the Watchdog can alternatively be used to reset only the Multiplexer to the default state (all output lines off), see SERVICE_WDT_RESET_TYPE. The function WatchdogHasFired() can then be used to check the state of the watchdog.

Firmware Update

Firmware updates are normally provided by IMAGO as separate packages which can be executed on the system. The function FirmwareUpdate() can alternatively be used to update the firmware within the user application.

This function is not supported by the following platforms. The firmware is provided as Debian packages instead:

  • VisionCam XM
  • VisionSensor PV
  • VisionBox DAYTONA
Note
  • A system may contain multiple hardware entities which have to be updated separately.
  • Using the incorrect firmware file can lead to inoperative hardware. Contact IMAGO for choosing the right files.
  • The update process can take up to one minute. Don't interrupt the process.
  • After success, the power supply for most systems must be reapplied before the new firmware is used.

Public Types

enum  SERVICE_WDT_RESET_TYPE
 Configures the reset behavior of the watchdog, used by WatchdogSetup() More...
 

Public Member Functions

bool FirmwareUpdate (const unsigned char *pFirmwareData, const size_t FileSize)
 Executes an update of the firmware for the hardware entity. More...
 
bool GetFanNumberOfChannels (unsigned int &NumberOfChannels)
 Returns the number of possible fan channels. More...
 
bool GetFanSpeed (const unsigned int ChannelIndex, unsigned int &RPM)
 Return the current fan speed for the given index. More...
 
bool GetSerialNumber (char pSerialnumber[32])
 Returns the serial number for the hardware entity. More...
 
bool GetSystemTemperature (float &fTemperature)
 Returns system temperature. More...
 
bool Reset ()
 Resets the device to default settings. More...
 
 Service ()
 Default constructor for the device object More...
 
bool SetFanTargetTemperature (unsigned int Temperature)
 Sets the target temperature of the fan regulation. More...
 
bool WatchdogHasFired (bool &HasFired)
 Returns the state of the Watchdog. More...
 
bool WatchdogService ()
 Sends a signal to the FPGA which resets the watchdog timer. More...
 
bool WatchdogSetup (bool boEnable, unsigned int msTimeout)
 Configures the FPGA watchdog. More...
 
bool WatchdogSetup (bool boEnable, unsigned int msTimeout, SERVICE_WDT_RESET_TYPE ResetType)
 Configures the watchdog and the reset behavior. More...
 
- Public Member Functions inherited from VIB::iDevice
bool Close ()
 Closes a device More...
 
 iDevice (const iDevice &device)
 The copy constructor makes a copy of the existing device object More...
 
bool isOpen (bool &state)
 Returns the open state of a device object More...
 
bool Open (unsigned int Index=0)
 Opens a device More...
 
iDeviceoperator= (const iDevice &device)
 The assignment operator makes a copy of the existing device object More...
 
virtual ~iDevice ()
 Deletes the device object More...
 

Member Enumeration Documentation

◆ SERVICE_WDT_RESET_TYPE

Configures the reset behavior of the watchdog, used by WatchdogSetup()

Enumerator
SERVICE_WDT_RESET_TYPE_REBOOT 

Cold reset of the system using a hardware reset signal.

SERVICE_WDT_RESET_TYPE_MULTIPLEXER 

The output signals of the Multiplexer are reset to the default state.

Constructor & Destructor Documentation

◆ Service()

VIB::Service::Service ( )

Default constructor for the device object

The device must be opened with Open() before it can be used.

Member Function Documentation

◆ FirmwareUpdate()

bool VIB::Service::FirmwareUpdate ( const unsigned char *  pFirmwareData,
const size_t  FileSize 
)

Executes an update of the firmware for the hardware entity.

This function can be used to update the firmware within the user application.

Parameters
pFirmwareDataPointer to buffer holding the firmware data
FileSizeNumber of valid bytes in the buffer
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetFanNumberOfChannels()

bool VIB::Service::GetFanNumberOfChannels ( unsigned int &  NumberOfChannels)

Returns the number of possible fan channels.

The number of installed fans can be lower.

Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetFanSpeed()

bool VIB::Service::GetFanSpeed ( const unsigned int  ChannelIndex,
unsigned int &  RPM 
)

Return the current fan speed for the given index.

Parameters
ChannelIndexFan index, 0 ... (GetFanNumberOfChannels() - 1)
RPMCurrent speed in RPM
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetSerialNumber()

bool VIB::Service::GetSerialNumber ( char  pSerialnumber[32])

Returns the serial number for the hardware entity.

The function will return a null-terminated string like "AGEX1109000012". See section Serial Number for a detailed description and example code.

Parameters
pSerialnumberValid string pointer for storing the serial number
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetSystemTemperature()

bool VIB::Service::GetSystemTemperature ( float &  fTemperature)

Returns system temperature.

Parameters
fTemperatureTemperature in °C
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ Reset()

bool VIB::Service::Reset ( )

Resets the device to default settings.

  • The Watchdog is disabled
  • VisionBox AGE-X1: the fan target temperature is set to 45 °C
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetFanTargetTemperature()

bool VIB::Service::SetFanTargetTemperature ( unsigned int  Temperature)

Sets the target temperature of the fan regulation.

Remember, a higher system temperature will reduce the noise but also reduces the life-time and decreases the ability for the CPU to use clock speeds above the base frequency.

Parameters
TemperatureTarget temperature in °C, 0 ... 50
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ WatchdogHasFired()

bool VIB::Service::WatchdogHasFired ( bool &  HasFired)

Returns the state of the Watchdog.

The function returns true if the watchdog timeout has expired. A reboot or any call to WatchdogSetup() resets the state.

Parameters
HasFiredWatchdog state
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ WatchdogService()

bool VIB::Service::WatchdogService ( )

Sends a signal to the FPGA which resets the watchdog timer.

Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ WatchdogSetup() [1/2]

bool VIB::Service::WatchdogSetup ( bool  boEnable,
unsigned int  msTimeout 
)

Configures the FPGA watchdog.

If the watchdog is enabled the program has to call WatchdogService() within the specified timeout period. If the timeout expires, a hardware system reset is triggered.

This function call is identical to WatchdogSetup(boEnable, msTimeout, SERVICE_WDT_RESET_TYPE_REBOOT).

The watchdog will not be disabled when the Service device is closed.

Parameters
boEnableEnable or disables the watchdog timer
msTimeoutWatchdog timeout in milliseconds (max. 40000)
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ WatchdogSetup() [2/2]

bool VIB::Service::WatchdogSetup ( bool  boEnable,
unsigned int  msTimeout,
SERVICE_WDT_RESET_TYPE  ResetType 
)

Configures the watchdog and the reset behavior.

This function is identical to the WatchdogSetup() except, that the reset type can be specified after the timeout expires.

Parameters
boEnableEnable or disables the watchdog timer
msTimeoutWatchdog timeout in milliseconds (max. 40000)
ResetTypeReset behavior
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description
VIB::SYST_BASEBOARD
@ SYST_BASEBOARD
Definition: VIB_Interface.h:107
VIB::DT_SERVICE
@ DT_SERVICE
Hardware service module → VIB::Service.
Definition: VIB_Interface.h:87
VIB::VIBSystem::CreateInstance
static bool CreateInstance(VIBSystem **ppVIBSystem)
Creates a factory instance for the mainboard.
Definition: VIBSystem.cpp:107
VIB
All relevant classes and functions are residing in this namespace.
Definition: VIB_Documentation_Main.txt:2
VIB::Service::WatchdogSetup
bool WatchdogSetup(bool boEnable, unsigned int msTimeout)
Configures the FPGA watchdog.
Definition: Service.cpp:498
VIB::Service::GetSystemTemperature
bool GetSystemTemperature(float &fTemperature)
Returns system temperature.
Definition: Service.cpp:412
VIB::Service
This class contains functions associated with the hardware component (serial number,...
Definition: VIB_Interface.h:571
VIB::Service::GetSerialNumber
bool GetSerialNumber(char pSerialnumber[32])
Returns the serial number for the hardware entity.
Definition: Service.cpp:466
VIB::Service::WatchdogService
bool WatchdogService()
Sends a signal to the FPGA which resets the watchdog timer.
Definition: Service.cpp:542
VIB::VIBSystem
The factory for devices.
Definition: VIB_Interface.h:214
VIB::iDevice::Open
bool Open(unsigned int Index=0)
Opens a device
Definition: iDevice.cpp:109