From 5aa541a9e87019895dc4c11d0045ed269a247e04 Mon Sep 17 00:00:00 2001
From: Martin Braun <martin.braun@ettus.com>
Date: Thu, 19 Jul 2018 16:33:18 -0700
Subject: docs: Add page for the Python API

---
 host/docs/build.dox     |  2 +-
 host/docs/pythonapi.dox | 85 +++++++++++++++++++++++++++++++++++++++++++++++++
 host/docs/uhd.dox       |  1 +
 3 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 host/docs/pythonapi.dox

(limited to 'host/docs')

diff --git a/host/docs/build.dox b/host/docs/build.dox
index a022985a8..9a6beba20 100644
--- a/host/docs/build.dox
+++ b/host/docs/build.dox
@@ -57,7 +57,7 @@ Other compilers (or lower versions) may work, but are unsupported.
 
 ### Python
 
-- **Purpose:** used by mako and utility scripts
+- **Purpose:** Used by mako build time,  and utility scripts and the Python API at runtime
 - **Minimum Version:** 2.7
 - **Usage:** build time + runtime utility scripts (required)
 - **Download URL:** http://www.python.org/download/
diff --git a/host/docs/pythonapi.dox b/host/docs/pythonapi.dox
new file mode 100644
index 000000000..d31cba9a6
--- /dev/null
+++ b/host/docs/pythonapi.dox
@@ -0,0 +1,85 @@
+/*! \page page_python Python API
+
+UHD supports a Python API, in case the C++ or C APIs are not the right solution
+for your application.
+
+\section python_install Installing the Python API
+
+In order to install the Python API when building UHD from source, make sure all
+the dependencies are available (see also \ref page_build_guide, you need
+Boost.Python from your Boost library). Make sure you have the CMake variable
+`ENABLE_PYTHON_API` set to ON (e.g., by running `cmake -DENABLE_PYTHON_API=ON`).
+
+\subsection python_install_2v3 Python 2 vs. 3
+
+The Python API supports both Python 2 and 3, but if you have both versions
+installed, CMake might require some hints which version is the desired one.
+To force Python 3, UHD has a CMake variable `ENABLE_PYTHON3`
+
+\section python_usage Using the Python API
+
+The Python API mirrors the C++ API, so the C++ reference manual can be used to
+understand the behaviour of the Python API as well.
+
+Names in the Python API have been modified to follow a PEP8-compatible naming
+convention, for example, uhd::usrp::multi_usrp in C++ corresponds to
+uhd.usrp.MultiUSRP in Python (this makes UHD/Python code implicitly compatible
+with most linters, but it also has the side-effect of hiding symbols that get
+imported from the C++ domain).
+The following two snippets are equivalent. First the C++ version:
+~~~{.cpp}
+#include <uhd/usrp/multi_usrp.hpp>
+
+// ...
+
+auto usrp = uhd::usrp::multi_usrp::make("type=b200");
+usrp->set_rx_freq(100e6);
+~~~
+
+Now the Python version:
+~~~{.py}
+import uhd
+
+# ...
+
+usrp = uhd.usrp.MultiUSRP("type=b200")
+usrp.set_rx_freq(100e6)
+~~~
+
+Not all API calls from the C++ API are also supported in the Python API, and
+the Python API has some additional functions that are not available in C++, but
+for the most part, the `uhd::usrp::multi_usrp` API is identical.
+
+\section python_usage_oneoff One-off transmit/receive applications
+
+A common type of Python-based SDR applications are those which produce or
+consume a limited number of samples. For example, an application could receive a
+second's worth of samples, then do offline processing, print the result, and
+exit. For this case, convenience API calls were added to the Python API. The
+following snippet is an example of how to store 1 second of samples acquired at
+1 Msps:
+
+~~~{.py}
+import uhd
+
+def recv_to_file():
+    """RX samples and write to file"""
+    usrp = uhd.usrp.MultiUSRP("type=b200")
+    num_samps = 1e6
+    if not isinstance(args.channels, list):
+        args.channels = [args.channels]
+    samps = usrp.recv_num_samps(
+        1e6, # Number of samples
+	2.4e9, # Frequency in Hz
+	1e6, # Sampling rate
+	[0], # Receive on channel 0
+	80, # 80 dB of RX gain
+    )
+    samps.tofile('samples.dat')
+~~~
+
+This kind of API is particularly useful in combination with Jupyter Notebooks or
+similar interactive environments.
+
+*/
+// vim:ft=doxygen:
diff --git a/host/docs/uhd.dox b/host/docs/uhd.dox
index 099bbe415..deca32599 100644
--- a/host/docs/uhd.dox
+++ b/host/docs/uhd.dox
@@ -9,6 +9,7 @@ publically available symbol in the UHD namespace.
 
 Some additional pages on developing UHD are also available here:
 
+\li \subpage page_python
 \li \subpage page_coding
 \li \subpage page_converters
 \li \subpage page_stream
-- 
cgit v1.2.3