DGILib
USER GUIDE
Atmel-42771A-DGILib_User Guide-09/2016
Table of Contents
1. Description.................................................................................................................3
2. API.............................................................................................................................4
2.1. Discovery......................................................................................................................................4
2.1.1. initialize_status_change_notification............................................................................. 4
2.1.2. uninitialize_status_change_notification......................................................................... 4
2.1.3. register_for_device_status_change_notifications..........................................................4
2.1.4. unregister_for_device_status_change_notifications......................................................5
2.1.5. discover......................................................................................................................... 5
2.1.6. get_device_count...........................................................................................................5
2.1.7. get_device_name.......................................................................................................... 5
2.1.8. get_device_serial...........................................................................................................5
2.1.9. is_msd_mode................................................................................................................ 6
2.1.10. set_mode....................................................................................................................... 6
2.2. Housekeeping...............................................................................................................................6
2.2.1. connect.......................................................................................................................... 6
2.2.2. disconnect......................................................................................................................6
2.2.3. connection_status..........................................................................................................7
2.2.4. get_major_version......................................................................................................... 7
2.2.5. get_minor_version......................................................................................................... 7
2.2.6. get_build_number.......................................................................................................... 7
2.2.7. get_fw_version...............................................................................................................7
2.2.8. start_polling................................................................................................................... 8
2.2.9. stop_polling....................................................................................................................8
2.2.10. target_reset....................................................................................................................8
2.3. Interface Communication..............................................................................................................8
2.3.1. interface_list...................................................................................................................8
2.3.2. interface_enable............................................................................................................ 9
2.3.3. interface_disable............................................................................................................9
2.3.4. interface_get_configuration........................................................................................... 9
2.3.5. interface_set_configuration..........................................................................................10
2.3.6. interface_clear_buffer.................................................................................................. 10
2.3.7. interface_read_data.....................................................................................................10
2.3.8. interface_write_data.....................................................................................................11
2.4. Auxiliary...................................................................................................................................... 11
2.4.1. Power...........................................................................................................................11
3. Revision History.......................................................................................................16
Atmel DGILib [USER GUIDE]
Atmel-42771A-DGILib_User Guide-09/2016
2
1. Description
DGILib is a Dynamic-Link Library (DLL) to help software applications communicate with Data Gateway
Interface (DGI) devices. See the Data Gateway Interface user guide for further details. DGILib handles
the low-level USB communication and adds a level of buffering for minimizing the chance of overflows.
The library helps parse data streams of high complexity. The timestamp interface is parsed and split into
separate buffers for each data source. The power interface is optionally parsed and calibrated using an
auxiliary API.
Atmel DGILib [USER GUIDE]
Atmel-42771A-DGILib_User Guide-09/2016
3
2. API
The API functions are separated into four groups:
Discovery Used to discover available devices and get information about them.
Housekeeping Provides version information, connection, and session control.
Interface Communication Handles communication with the various interfaces of DGI.
Auxiliary Extended functionality with interface-specifc usage.
2.1. Discovery
2.1.1. initialize_status_change_notification
Initializes the system necessary for using the status change notification callback mechanisms. A handle
will be created to keep track of the registered callbacks. This function must always be called before
registering and unregistering notification callbacks.
Function definition
void initialize_status_change_notification(uint32_t* handlep)
Parameters
handlep Pointer to a variable that will hold the handle
2.1.2. uninitialize_status_change_notification
Uninitializes the status change notification callback mechanisms. This function must be called when
shutting down to clean up memory allocations.
Function definition
void uninitialize_status_change_notification(uint32_t handle)
Parameters
handle Handle to uninitialize
2.1.3. register_for_device_status_change_notifications
Registers provided function pointer with the device status change mechanism. Whenever there is a
change (device connected or disconnected) the callback will be executed. Note that it is not allowed to
connect to a device in the context of the callback function. The callback function has the following
definition: typedef void (*DeviceStatusChangedCallBack)(char* device_name, char* device_serial, BOOL
connected)
Function definition
void register_for_device_status_change_notifications(uint32_t handle, DeviceStatusChangedCallBack
deviceStatusChangedCallBack)
Parameters
handle Handle to change notification mechanisms
deviceStatusChangedCallBack Function pointer that will be called when the devices change
Atmel DGILib [USER GUIDE]
Atmel-42771A-DGILib_User Guide-09/2016
4
2.1.4. unregister_for_device_status_change_notifications
Unregisters previously registered function pointer from the device status change mechanism.
Function definition
void unregister_for_device_status_change_notifications(uint32_t handle, DeviceStatusChangedCallBack
deviceStatusChangedCallBack)
Parameters
handle Handle to change notification mechanisms
deviceStatusChangedCallBack Function pointer that will be removed
2.1.5. discover
Triggers a scan to find available devices in the system. The result will be immediately available through
the get_device_count, get_device_name and get_device_serial functions.
Function definition
void discover(void)
Parameters
2.1.6. get_device_count
Returns the number of devices detected.
Function definition
int get_device_count(void)
Parameters
2.1.7. get_device_name
Gets the name of a detected device.
A non-zero return value indicates an error.
Function definition
int get_device_name(int index, char* name)
Parameters
index Index of device ranges from 0 to get_device_count - 1
name Pointer to buffer where name of device can be stored. 100 or more bytes must be allocated
2.1.8. get_device_serial
Gets the serial number of a detected device.
A non-zero return value indicates an error.
Function definition
int get_device_serial(int index, char* sn)
Parameters
index Index of device ranges from 0 to get_device_count - 1
Atmel DGILib [USER GUIDE]
Atmel-42771A-DGILib_User Guide-09/2016
5
sn Pointer to buffer where the serial number of the device can be stored. 100 or more bytes must be
allocated. This is used when connecting to a device.
2.1.9. is_msd_mode
EDBG devices can be set to a mass storage mode where the DGI is unavailable. In such cases the
device is still detected by DGILib, but it won't be possible to directly connect to it. This command is used
to check if the device is in such a mode.
A non-zero return value indicates that the mode must be changed by set_mode before proceeding.
Function definition
int is_msd_mode(char* sn)
Parameters
sn Serial number of the device to check
2.1.10. set_mode
This function is used to temporarily set the EDBG to a specified mode.
A non-zero return value indicates an error.
Function definition
int set_mode(char* sn, int nmbed)
Parameters
sn Serial number of the device to set
nmbed 0 - Set to mbed mode. 1 - Set to DGI mode.
2.2. Housekeeping
2.2.1. connect
Opens a connection to the specified device. This function must be called prior to any function requiring
the connection handle.
A non-zero return value indicates an error.
Function definition
int connect(char* sn, uint32_t* dgi_hndl_p)
Parameters
sn Buffer holding the serial number of the device to open a connection to
dgi_hndl_p Pointer to a variable that will hold the handle of the connection
2.2.2. disconnect
Closes the specified connection.
A non-zero return value indicates an error.
Atmel DGILib [USER GUIDE]
Atmel-42771A-DGILib_User Guide-09/2016
6
Loading...