{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "01804aa4-b906-4ae7-a26b-b7d758a9808a",
   "metadata": {},
   "source": [
    "# Device Communication Basics\n",
    "\n",
    "## Overview\n",
    "This document covers the basics of device communication and configuration. OpenSync devices employ USB on-the-go (OTG), so no drivers are necessary to communicate with an OpenSync device. This is beneficial as device discovery revolves arounds a computer's ability to detect a USB device that is actively connected to the computer.\n",
    "\n",
    "## Purpose\n",
    "This example demonstrates how to search, connect, and \"talk\" to an OpenSync device. OpenSync relies on a stable USB connection, so make sure one is present for this demonstration."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "957d6b8f-b96e-4621-832c-fa45269cc63b",
   "metadata": {},
   "source": [
    "## Imports\n",
    "To begin, import opensync as such."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "cba7fbad-6454-4c34-bed6-e471d279d9cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "import opensync"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6290f546-7af6-480d-8e64-da796161eecc",
   "metadata": {},
   "source": [
    "## Device Connection\n",
    "We need to search for any OpenSync devices to connect to. This is performed by the function `device_comm_search`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "29e36c55-54c9-47f9-83d5-0baea756b051",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['COM7']"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "avail_ports = opensync.device_comm_search()\n",
    "avail_ports"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1afe9e25-b7a3-4bda-ac16-2e8e0862657b",
   "metadata": {},
   "source": [
    "There are two ways we can open a connection once we found the correct port to connect to. We can manually manage the resources with `device_comm_open` and `device_comm_close` or use context managers to automatically manage resources with `device_comm_managed`. Both methods will be shown in this document. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2bae0265-7de8-4f7e-b219-f198184f59f5",
   "metadata": {},
   "source": [
    "### Manually Open Device Connection\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "b2a6f273-072a-4688-8e62-843b1baefb64",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Serial<id=0x18968321ea0, open=True>(port='COM7', baudrate=19200, bytesize=8, parity='N', stopbits=1, timeout=0.1, xonxoff=False, rtscts=False, dsrdtr=False)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Open USB port\n",
    "sync_device = opensync.device_comm_open(avail_ports[0])\n",
    "sync_device"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "5b41533a-6471-4357-9181-81206029dbb8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['OpenPIV', 'OpenSync', '5A3F6CE6128EEB36', '0.7.3']\n",
      "['IDLE']\n"
     ]
    }
   ],
   "source": [
    "# Get device state and version\n",
    "print(opensync.device_system_version(sync_device))\n",
    "print(opensync.device_system_status(sync_device))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "12651e79-ca0e-4ce1-a456-65e10d8f3aec",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Close USB port\n",
    "opensync.device_comm_close(sync_device)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29fd2057-bd1b-4cc9-91a3-8c5cb4cb1dd2",
   "metadata": {},
   "source": [
    "### Open with Context Manager"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "df867e3e-e5d5-4540-a544-e76e7836ce69",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['OpenPIV', 'OpenSync', '5A3F6CE6128EEB36', '0.7.3']\n",
      "['IDLE']\n"
     ]
    }
   ],
   "source": [
    "with opensync.device_comm_managed(avail_ports[0]) as sync_device:\n",
    "    # Get device state and version\n",
    "    print(opensync.device_system_version(sync_device))\n",
    "    print(opensync.device_system_status(sync_device))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24c9d278-a5a0-4c7d-9f6b-78fc794a1c1b",
   "metadata": {},
   "source": [
    "## Status Information\n",
    "OpenSync allows one to poll system status information even when running a pulse sequence. Below are the most commonly used requests."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "29a7d47c-ee68-4691-9e51-ca87e0b397dc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['OpenPIV', 'OpenSync', '5A3F6CE6128EEB36', '0.7.3']\n",
      "['IDLE']\n",
      "['pll_sys = 250000kHz', 'pll_usb = 48000kHz', 'rosc = 10180kHz', 'clk_sys = 250000kHz', 'clk_peri = 48000kHz', 'clk_usb = 48000kHz', 'clk_adc = 48000kHz']\n"
     ]
    }
   ],
   "source": [
    "with opensync.device_comm_managed(avail_ports[0]) as sync_device:\n",
    "    print(opensync.device_system_version(sync_device))\n",
    "    print(opensync.device_system_status(sync_device))\n",
    "    print(opensync.device_system_freq(sync_device))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9974e0f1-43eb-4929-8b60-4566bd024857",
   "metadata": {},
   "source": [
    "## Executing Device Parameters\n",
    "Two of the more important functions for OpenSync are `device_system_fire` and `device_system_stop`. `device_system_fire` executes a pulse sequence with the current pulse and clock configrations. To prematurely stop a pulse sequence iteration, one can use `device_system_stop` and an abort signal will be sent to the OpenSync device."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}