dox: update the mainpage of the generated dox

with some info about scan contexts and how to use them. Signed-off-by: Robin Getz <[email protected]>
analogdevicesinc · Jun 5, 2020 · ac92604 · ac92604
1 parent 268c968
commit ac92604
Showing 1 changed file with 9 additions and 0 deletions.
diff --git a/mainpage.dox b/mainpage.dox
@@ -26,11 +26,20 @@ The basic bricks of the libiio API are the iio_context, iio_device, iio_channel
 - A iio_device object may contain zero or more iio_channel objects. A iio_channel object is associated with only one iio_device.
 - A iio_device object may be associated with one iio_buffer object, and a iio_buffer object is associated with only one iio_device.
 
+@section scan_contexts Scanning for IIO contexts
+The first step when dealing with a collection of IIO devices (known as a context) is to find the context. This can be connected via usb, network, serial or local. Having these different connectivity options could prove to be problematic, but libiio abstracts the low level communications away, and allows you just to find contexts, and talk to devices without being interested in the low level aspects. Many find this convinent to develop applications and algorithms on a host, and quickly move to an embedded Linux system without having to change any code.
+
+To find what IIO contexts are available, use the following:
+- iio_create_scan_context(): Create a iio_scan_context object. Depending on what backends were enabled with compiling the library, some of them may not be available. The first argument to this function is a string which is used as a filter ("usb:", "ip:", "local:", "usb:ip", where the default (NULL) means any backend that is compiled in).
+- iio_scan_context_get_info_list(): get the iio_context_info object from the iio_scan_context object. The iio_context_info object can be examined with the iio_context_info_get_description() and iio_context_info_get_uri() to determine which uri you want to attach to.
+
 @section creating_context Creating a context
 Different functions are available to create the iio_context object. Depending on what backends were enabled when compiling the library, some of them may not be available.
 Each function will result in a different backend being used.
 
 Those functions are:
+- iio_create_context_from_uri(): This should be the main function to create contexts, which takes a Uniform Resource Identifier (uri), and returns a iio_context.
+- iio_create_default_context(): Create a "local" context if we can, otherwise use the ENV_VAR IIOD_REMOTE.
 - iio_create_local_context(): Create a "local" context, to use the IIO devices connected to the system (typically for cross-compiled applications).
 - iio_create_network_context(): Create a "network" context that will work with a remotely connected target.