DGILib - Microchip Technology

1 DGILib USER GUIDEA tmel-42771A-DGILib_User Guide-09/2016 Table of DGILib [USER GUIDE]Atmel-42771A-DGILib_User Guide-09/201621. DescriptionDGILib is a Dynamic-Link Library (DLL) to help software applications communicate with Data GatewayInterface (DGI) devices. See the Data Gateway Interface user guide for further details. DGILib handlesthe low-level USB communication and adds a level of buffering for minimizing the chance of library helps parse data streams of high complexity. The timestamp interface is parsed and split intoseparate buffers for each data source. The power interface is optionally parsed and calibrated using anauxiliary DGILib [USER GUIDE]Atmel-42771A-DGILib_User Guide-09/201632.

2 APIThe API functions are separated into four groups:DiscoveryUsed to discover available devices and get information about version information, connection, and session CommunicationHandles communication with the various interfaces of functionality with interface-specifc initialize_status_change_notificationIni tializes the system necessary for using the status change notification callback mechanisms. A handlewill be created to keep track of the registered callbacks. This function must always be called beforeregistering and unregistering notification definitionvoid initialize_status_change_notification(ui nt32_t* handlep)ParametershandlepPointer to a variable that will hold the uninitialize_status_change_notificationU ninitializes the status change notification callback mechanisms.

3 This function must be called whenshutting down to clean up memory definitionvoid uninitialize_status_change_notification( uint32_t handle)ParametershandleHandle to register_for_device_status_change_notifi cationsRegisters provided function pointer with the device status change mechanism. Whenever there is achange (device connected or disconnected) the callback will be executed. Note that it is not allowed toconnect to a device in the context of the callback function. The callback function has the followingdefinition: typedef void (*DeviceStatusChangedCallBack)(char* device_name, char* device_serial, BOOL connected)Function definitionvoid register_for_device_status_change_notifi cations(uint32_t handle, DeviceStatusChangedCallBackdeviceStatusC hangedCallBack)

4 ParametershandleHandle to change notification mechanismsdeviceStatusChangedCallBackFun ction pointer that will be called when the devices changeAtmel DGILib [USER GUIDE]Atmel-42771A-DGILib_User Guide-09 unregister_for_device_status_change_noti ficationsUnregisters previously registered function pointer from the device status change definitionvoid unregister_for_device_status_change_noti fications(uint32_t handle, DeviceStatusChangedCallBackdeviceStatusC hangedCallBack)ParametershandleHandle to change notification mechanismsdeviceStatusChangedCallBackFun ction pointer that will be discoverTriggers a scan to find available devices in the system. The result will be immediately available throughthe get_device_count, get_device_name and get_device_serial definitionvoid discover(void) get_device_countReturns the number of devices definitionint get_device_count(void) get_device_nameGets the name of a detected non-zero return value indicates an definitionint get_device_name(int index, char* name)ParametersindexIndex of device ranges from 0 to get_device_count - 1namePointer to buffer where name of device can be stored.

5 100 or more bytes must be get_device_serialGets the serial number of a detected non-zero return value indicates an definitionint get_device_serial(int index, char* sn)ParametersindexIndex of device ranges from 0 to get_device_count - 1 Atmel DGILib [USER GUIDE]Atmel-42771A-DGILib_User Guide-09/20165snPointer to buffer where the serial number of the device can be stored. 100 or more bytes must beallocated. This is used when connecting to a is_msd_modeEDBG devices can be set to a mass storage mode where the DGI is unavailable. In such cases thedevice is still detected by DGILib , but it won't be possible to directly connect to it. This command is usedto check if the device is in such a non-zero return value indicates that the mode must be changed by set_mode before definitionint is_msd_mode(char* sn)ParameterssnSerial number of the device to set_modeThis function is used to temporarily set the EDBG to a specified non-zero return value indicates an definitionint set_mode(char* sn, int nmbed)ParameterssnSerial number of the device to setnmbed0 - Set to mbed mode.

6 1 - Set to DGI connectOpens a connection to the specified device. This function must be called prior to any function requiringthe connection non-zero return value indicates an definitionint connect(char* sn, uint32_t* dgi_hndl_p)ParameterssnBuffer holding the serial number of the device to open a connection todgi_hndl_pPointer to a variable that will hold the handle of the disconnectCloses the specified non-zero return value indicates an DGILib [USER GUIDE]Atmel-42771A-DGILib_User Guide-09/20166 Function definitionint disconnect(uint32_t dgi_hndl)Parametersdgi_hndlHandle of the connection_statusVerifies that the specified connection is still non-zero return value indicates an definitionint connection_status(uint32_t* dgi_hndl)Parametersdgi_hndlHandle of the get_major_versionA non-zero return value indicates an definitionint get_major_version(void) get_minor_versionA non-zero return value indicates an definitionint get_minor_version(void) get_build_numberReturns the build number of DGILib .

7 If not supported, returns definitionint get_build_number(void) get_fw_versionGets the firmware version of the DGI device connected. Note that this is the version of the DGI device,and not the non-zero return value indicates an definitionint get_fw_version(uint32_t dgi_hndl, unsigned char* major, unsigned char* minor)Parametersdgi_hndlHandle of the connectionAtmel DGILib [USER GUIDE]Atmel-42771A-DGILib_User Guide-09/20167majorPointer to a variable where the major version will be storedminorPointer to a variable where the minor version will be start_pollingThis function will start the polling system and start acquisition on enabled interfaces.

8 It is possible toenable/disable interfaces both before and after the polling has been started. However, no data will betransferred until the polling is non-zero return value indicates an definitionint start_polling(uint32_t dgi_hndl)Parametersdgi_hndlHandle of the stop_pollingThis function will stop the polling system and stop acquisition on all non-zero return value indicates an definitionint stop_polling(uint32_t dgi_hndl)Parametersdgi_hndlHandle of the target_resetThis function is used to control the state of the reset line connected to the target, if non-zero return value indicates an definitionint target_reset(uint32_t dgi_hndl, bool hold_reset)

9 Parametersdgi_hndlHandle of the connectionhold_resetTrue will assert reset, false will release Interface interface_listQueries the connected DGI device for available interfaces. Refer to the DGI documentation to resolve non-zero return value indicates an definitionint interface_list(uint32_t dgi_hndl, unsigned char* interfaces, unsigned char* count)Atmel DGILib [USER GUIDE]Atmel-42771A-DGILib_User Guide-09/20168 Parametersdgi_hndlHandle to connectioninterfacesBuffer to hold the ID of the available interfaces. Should be able to hold minimum 10elements, but a larger count should be used to be future to a variable that will be set to the number of interfaces registered in interface_enableEnables the specified interface.

10 Note that no data acquisition will begin until a session has been non-zero return value indicates an definitionint interface_enable(uint32_t dgi_hndl, int interface_id, bool timestamp)Parametersdgi_hndlHandle to connectioninterface_idThe ID of the interface to enabletimestampSetting this to true will make the interface use timestamping. Consult the DGIdocumentation for details on the timestamping interface_disableDisables the specified non-zero return value indicates an definitionint interface_disable(uint32_t dgi_hndl, int interface_id)Parametersdgi_hndlHandle to connectioninterface_idThe ID of the interface to interface_get_configurationGets the configuration associated with the specified interface.