.. _usage:

############
Basic Usage
############

This section seeks to provide a simple example of how to interact with the reservoir as well as some background on other basic functionality provided for interacting with the device.

.. include:: sine_wave.rst

*******************
System Information
*******************


In order to obtain system information the package provides the method :meth:`emucore_direct.client.EmuCoreClient.system_info`.
An example of how to call this function is provided below:

.. code:: python

   from emucore_direct.client import EmuCoreClient
   # replace with your network location
   IP_ADDR = "YOUR DEVICE IP ADDRESS"
   PORT = "YOUR DEVICE PORT"
   # Instantiate an EmuCore instance
   ec_client = EmuCoreClient(ip_addr=IP_ADDR, port = PORT)
   ec_client.system_info()
   # Example output:
   # {'system_name': 'Bumblebee', 'system_version': 'v0.1-10-ga4a5c1f'}

.. code:: python

*******************
Device Lock Basics
*******************

Device locking ensures that only one process is running on the device at a time. In order to ensure this functionality, there are a few useful functions:

  * :meth:`emucore_direct.client.EmuCoreClient.acquire_lock`---makes a single attempt to acquire the device lock
  * :meth:`emucore_direct.client.EmuCoreClient.release_lock`---releases lock if lock currently held by the user.
  * :meth:`emucore_direct.client.EmuCoreClient.check_lock`---checks device lock status without attempting to acquire lock
  * :meth:`emucore_direct.client.EmuCoreClient.wait_for_lock`---waits for device lock indefinitely

In order to ensure access to users there is a timer on the server that if a user is inactive for more than one minute and another user wishes to use the device they will be able to acquire the device
lock and the previous idle user will lose it's lock on the device. In order to help ease the process of acquiring the lock it's recommended to use
:meth:`emucore_direct.client.EmuCoreClient.wait_for_lock`. In order to ensure maximum device availability it is a good practice to release the lock if taking time between runs on the device. Here is a basic example of how to use :meth:`emucore_direct.client.EmuCoreClient.wait_for_lock` and :meth:`emucore_direct.client.EmuCoreClient.release_lock`:

.. code::

   from emucore_direct.client import EmuCoreClient
   # replace with your network location
   IP_ADDR = "YOUR DEVICE IP ADDRESS"
   PORT = "YOUR DEVICE PORT"
   # Instantiate an EmuCore instance
   ec_client = EmuCoreClient(ip_addr=IP_ADDR, port = PORT)
   lock_id, _, _ = ec_client.wait_for_lock()
   ec_client.release_lock(lock_id=lock_id)
