From 6498fd6eb19cb03e1044e34e15812b185bacdf42 Mon Sep 17 00:00:00 2001
From: Jacob Williamson <jacob.williamson@diamond.ac.uk>
Date: Mon, 26 Jan 2026 14:12:08 +0000
Subject: [PATCH] Add simple turorial on how to use the config client inside
 dodal.

---
 docs/tutorials/config-server-example.ipynb | 154 +++++++++++++++++++++
 1 file changed, 154 insertions(+)
 create mode 100644 docs/tutorials/config-server-example.ipynb

diff --git a/docs/tutorials/config-server-example.ipynb b/docs/tutorials/config-server-example.ipynb
new file mode 100644
index 0000000000..7e54229a0a
--- /dev/null
+++ b/docs/tutorials/config-server-example.ipynb
@@ -0,0 +1,154 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "064a462a",
+   "metadata": {},
+   "source": [
+    "This is a simple tutorial on how to use the daq config server client inside dodal. \n",
+    "\n",
+    "The config server should already be installed in your venv. Import the client."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fe773296",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from daq_config_server.client import ConfigServer"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "03719820",
+   "metadata": {},
+   "source": [
+    "The config server is deployed centrally in Argus. The end point for this is https://daq-config.diamond.ac.uk, but you could also deploy an version of the config server elsewhere, such as on a beamline cluster.\n",
+    "\n",
+    "Initialise an instance of the client with the appropriate endpoint."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0cbe84cf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "CONFIG_SERVER_ENDPOINT = \"https://daq-config.diamond.ac.uk\"\n",
+    "\n",
+    "config_server = ConfigServer(url=CONFIG_SERVER_ENDPOINT)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ae91dbfc",
+   "metadata": {},
+   "source": [
+    "For some files, converters exist in the server that convert the contents of the file to a standard `dict` format or `Pydantic` model. For example, a model has been created for detector distance lookup tables."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "500c3dca",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from daq_config_server.models import DetectorXYLookupTable"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4aa10347",
+   "metadata": {},
+   "source": [
+    "Now we can use the `get_file_contents` method to retrieve a config file's contents. Here you should provide the filepath of the file to read, and your desired return type."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5cd7beb4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "detector_config = config_server.get_file_contents(\n",
+    "    \"/dls_sw/i03/software/daq_configuration/lookup/DetDistToBeamXYConverter.txt\",\n",
+    "    DetectorXYLookupTable,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7434749f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "detector_config.get_column_names()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4d07b3a4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "detector_config.columns"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "49046142",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "detector_config.rows"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fcca77d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "detector_config.get_value(\"detector_distance_mm\", 800, \"beam_centre_y_mm\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3436ca4a",
+   "metadata": {},
+   "source": [
+    "For more information on the config server see https://diamondlightsource.github.io/daq-config-server/main/index.html"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "mx-bluesky",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}