# Python Wrapper

For programmatic interaction with the AMDC, a basic Python class is provided.

The Python class files are available in: `AMDC-Firmware/scripts/`.

## `AMDC.py`

This is the core class which represents the AMDC.
After instantiating it, users can use it to send commands to the AMDC and read the response.
It supports both UART and Ethernet physical links.

Create a single AMDC object simply by:

```python
from AMDC import AMDC

amdc = AMDC()
```

````{attention}
If you receive an error when trying to import AMDC, ensure that:
1. `pyserial` is installed (e.g., `conda install pyserial`)
2. `AMDC-Firmware/scripts/` is on your system path.

The `os.getcwd()` and `sys.path.append()` commands can be particularly helpful for resolving path issues. In an example private user repository with two subfolders:
```
my-AMDC-workspace/              <= master repo
    AMDC-Firmware/              <= AMDC-Firmware as library
    notebooks/                  <= Your Jupyter notebook lives here
```

Running the following commands at the start of the notebook / Python script will properly configure the path:
```python
import os
import pathlib as pl
import sys
repo_dir = pl.Path(os.path.dirname(os.getcwd()))
sys.path.append(str(repo_dir / 'AMDC-Firmware' / 'scripts'))
from AMDC import AMDC
#...
```
````

Next, configure the `amdc` object based on if UART or Ethernet is used.

### Configuring UART Mode

```python
# After creating the amdc object...

# Set comm defaults for UART
amdc.setup_comm_defaults('uart')

# Init UART using the specified port (specific to each host PC)
amdc.uart_init('COM1')
```

### Configuring Ethernet Mode

```python
# After creating the amdc object...

# Set comm defaults for UART
amdc.setup_comm_defaults('eth')

# Init ethernet 
amdc.eth_init()

# Set up the default ASCII command socket
s0, s0_id = amdc.eth_new_socket('ascii_cmd')
amdc.eth_set_default_ascii_cmd_socket(s0)
```

### Connect / Disconnect

Both UART and Ethernet support notions of connecting and disconnecting from the AMDC.

- `amdc.connect()`
- `amdc.disconnect()`

For UART, this opens and closes the serial connection.

For Ethernet, connect does nothing since sockets are opened at creation.
Disconnect closes all open sockets.

```{warning}
Running `amdc.disconnect()` while using Ethernet will also close the default command socket, thus disabling the Ethernet interface.
To reconnect, you need to set up a new `ascii_cmd` socket and set the default command socket (as shown earlier).
```

### Sending Commands

After the initial configuration above, the AMDC object can be used without knowledge of the physical link.
Ethernet will simply have higher throughput.
Note that for simple commands, UART and Ethernet will appear to perform nearly the same (that is to say, fast).

To send commands, use the `amdc.cmd(cmd_str)` method where `cmd_str` is the character command text.

The `cmd()` method will send the characters to the AMDC over the configured link, then read the AMDC command response.
The method will block until the response is read, or a timeout is reached (default of 1 second).

The AMDC firmware is configured to run up to one command per time slice.
The default time slice is 100 usec, meaning the maximum theoretical command rate is 10 kHz.
In practice, users can expect command throughput well into the 100s of Hz.

### Customizing the AMDC Communication

The AMDC class supports customization of class parameters to change how the interface performs.

Customize the class after creating the `amdc` object.

#### Commands

- `amdc.comm_cmd_cmd_print` -- print the sending command to the console (default: `True`)
- `amdc.comm_cmd_cmd_print_prepend` -- prepend the sending command print with string (default: `"\t> "`)

#### Responses

- `amdc.comm_cmd_resp_capture` -- capture the response output from the command (default: `True`)
- `amdc.comm_cmd_resp_print` -- print the captured reponse to the console (default: `True`)
- `amdc.comm_cmd_resp_print_prepend` -- prepend the captured command response print with string (default: `""`)

#### Delays

- `amdc.comm_cmd_delay_cmd` -- delay after sending commands for given seconds (default: `0.001`)