# TigerASI
a feature-rich Python interface for ASI Tiger Controllers.
This driver was written to simplify the serial api to ASI's [Tiger Controllers](https://www.asiimaging.com/controllers/tiger-controller/) while reducing reliance on the full [documentation](https://asiimaging.com/docs/products/serial_commands) for most users.
Many (but not all!) commands have been exposed and wrapped in a simplified, self-consistent interface and documented for easy usage.
## Installation
To install this package from [PyPI](https://pypi.org/project/TigerASI/0.0.2/), invoke: `pip install TigerASI`.
To install this package from the github repository in editable mode, from this directory invoke `pip install -e .`
## Intro and Basic Usage
````python
from tigerasi.tiger_controller import TigerController
box = TigerController("COM4")
````
The basic command syntax looks like this:
````python
box.zero_in_place('x', 'y') # Zero out the specified axes at their current location.
box.move_absolute(x=1000, y=25) # Move to an absolute location in "stage units" (tenths of microns).
box.move_relative(z=100) # Move z +100 stage units in the positive z direction.
````
### Syntax Basics
All commands that reference stage axes accept a variable, optional number of arguments.
````python
box.zero_in_place('x') # only zeros the x axis. Other axes are ignored.
````
Stage axes are also case-insensitive,
````python
box.zero_in_place('X', 'y', 'Z') # also ok
````
and the order doesn't matter.
````python
box.zero_in_place('y', 'z', 'x') # also ok
````
All commands that query stage axes return a dict, keyed by *upper-case* stage axis.
````python
box.get_position('x', 'z', 'y')
# {'X': 100.0, 'Y': 305.0, 'Z': 10000.0}
````
Some commands can take an axis setting to be "current value" and another axis setting to be a specified value.
The syntax for these commands look like this:
````python
box.set_home('x', 'z', y=100.0) # Set x and z axes homing location to current spot. Set y axis to specific spot.
box.set_home('z', 'y', 'x', m=100.0, n=200.0) # variable number of arguments ok! order and case don't matter.
````
Some commands assume *all* axes if none are specified.
````python
box.zero_in_place() # will zero ALL lettered axes.
box.reset_lower_travel_limits() # will reset ALL lettered axes.
box.get_home() # will get ALL lettered axis home positions.
box.get_lower_travel_limits() # will get ALL lettered axis lower travel limits.
````
For setting values, this might not be your desired behavior, so it is safer to default to passing in axes explicitly.
````python
box.zero_in_place('x', 'y', 'z') # will zero only x, y, and z axes.
box.reset_lower_travel_limits('x', 'y', 'z') # will reset only x, y, and z axes.
````
When in doubt, check the docs.
## Simulation
This package also features a simulated version of the TigerController
````python
from tigerasi.sim_tiger_controller import SimTigerController
box = SimTigerController() # OR
box = SimTigerController('COM4') # com port is ignored. # OR
box = SimTigerController(build_config={'Motor Axes': ['X', 'Y', 'Z']})
# This object tracks its internal state for position and speed.
box.home_in_place('x', 'y', 'z') # home mocked axes.
box.move_absolute(z=10) # move mocked axis.
````
This feature can be useful for testing higher level code using the current api without the need to interact with real hardware.
## Advanced Usage
Many (but not all!) of ASI's more advanced features have been made available via this simplified API.
This list includes joystick enabling/disabling and remapping, setting stage travel limits, queuing moves into the hardware buffer, and many other more nuanced features.
For a breakdown of what commands have been exposed, have a look at the [examples folder](https://github.com/AllenNeuralDynamics/TigerASI/tree/main/examples) and the docs.
## Documentation
Docs can be generated via Sphinx.
Stay tuned for docs made available online.
## Implementation Details
### Blocking or Non-Blocking?
All commands to the Tigerbox return a reply.
Commands that query the Tigerbox state will also return data with that reply.
Waiting for a reply introduces 10-20[ms] of execution time before the function returns an 'ACK'knowledgement.
By default, methods *will block* until receiving this acknowledgement unless otherwise specified, like this:
````python
box.move_absolute(x=1000, y=25, wait=False) # will not block.
````
This behavior can only be used for commands to change the Tigerbox state.
Commands that query the Tigerbox state will always block until they receive a hardware reply.
Raw data
{
"_id": null,
"home_page": "https://github.com/AllenNeuralDynamics/TigerASI",
"name": "TigerASI",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "driver,asi,tigercontroller",
"author": "Joshua Vasquez",
"author_email": "joshua.vasquez@alleninstitute.org",
"download_url": "https://files.pythonhosted.org/packages/d9/50/c29422b7b28056b4c83c3578f482ec3c6247d9b604101339da58baa74fd0/TigerASI-0.0.9.tar.gz",
"platform": null,
"description": "# TigerASI\na feature-rich Python interface for ASI Tiger Controllers.\n\nThis driver was written to simplify the serial api to ASI's [Tiger Controllers](https://www.asiimaging.com/controllers/tiger-controller/) while reducing reliance on the full [documentation](https://asiimaging.com/docs/products/serial_commands) for most users.\nMany (but not all!) commands have been exposed and wrapped in a simplified, self-consistent interface and documented for easy usage.\n\n## Installation\nTo install this package from [PyPI](https://pypi.org/project/TigerASI/0.0.2/), invoke: `pip install TigerASI`.\n\nTo install this package from the github repository in editable mode, from this directory invoke `pip install -e .`\n\n## Intro and Basic Usage\n\n````python\nfrom tigerasi.tiger_controller import TigerController\n\nbox = TigerController(\"COM4\")\n````\n\nThe basic command syntax looks like this:\n````python\nbox.zero_in_place('x', 'y') # Zero out the specified axes at their current location.\nbox.move_absolute(x=1000, y=25) # Move to an absolute location in \"stage units\" (tenths of microns).\nbox.move_relative(z=100) # Move z +100 stage units in the positive z direction.\n````\n\n### Syntax Basics\nAll commands that reference stage axes accept a variable, optional number of arguments.\n````python\nbox.zero_in_place('x') # only zeros the x axis. Other axes are ignored.\n````\nStage axes are also case-insensitive,\n````python\nbox.zero_in_place('X', 'y', 'Z') # also ok\n````\nand the order doesn't matter.\n````python\nbox.zero_in_place('y', 'z', 'x') # also ok\n````\n\nAll commands that query stage axes return a dict, keyed by *upper-case* stage axis.\n````python\nbox.get_position('x', 'z', 'y')\n# {'X': 100.0, 'Y': 305.0, 'Z': 10000.0}\n````\n\nSome commands can take an axis setting to be \"current value\" and another axis setting to be a specified value.\nThe syntax for these commands look like this:\n````python\nbox.set_home('x', 'z', y=100.0) # Set x and z axes homing location to current spot. Set y axis to specific spot.\nbox.set_home('z', 'y', 'x', m=100.0, n=200.0) # variable number of arguments ok! order and case don't matter.\n````\n\nSome commands assume *all* axes if none are specified.\n````python\nbox.zero_in_place() # will zero ALL lettered axes.\nbox.reset_lower_travel_limits() # will reset ALL lettered axes.\n\nbox.get_home() # will get ALL lettered axis home positions.\nbox.get_lower_travel_limits() # will get ALL lettered axis lower travel limits.\n````\n\nFor setting values, this might not be your desired behavior, so it is safer to default to passing in axes explicitly.\n````python\nbox.zero_in_place('x', 'y', 'z') # will zero only x, y, and z axes.\nbox.reset_lower_travel_limits('x', 'y', 'z') # will reset only x, y, and z axes.\n````\nWhen in doubt, check the docs.\n\n## Simulation\nThis package also features a simulated version of the TigerController\n````python\nfrom tigerasi.sim_tiger_controller import SimTigerController\n\nbox = SimTigerController() # OR\nbox = SimTigerController('COM4') # com port is ignored. # OR\nbox = SimTigerController(build_config={'Motor Axes': ['X', 'Y', 'Z']})\n\n# This object tracks its internal state for position and speed.\nbox.home_in_place('x', 'y', 'z') # home mocked axes.\nbox.move_absolute(z=10) # move mocked axis.\n````\nThis feature can be useful for testing higher level code using the current api without the need to interact with real hardware.\n\n## Advanced Usage\nMany (but not all!) of ASI's more advanced features have been made available via this simplified API.\nThis list includes joystick enabling/disabling and remapping, setting stage travel limits, queuing moves into the hardware buffer, and many other more nuanced features.\nFor a breakdown of what commands have been exposed, have a look at the [examples folder](https://github.com/AllenNeuralDynamics/TigerASI/tree/main/examples) and the docs.\n\n## Documentation\nDocs can be generated via Sphinx.\nStay tuned for docs made available online.\n\n## Implementation Details\n\n### Blocking or Non-Blocking?\nAll commands to the Tigerbox return a reply.\nCommands that query the Tigerbox state will also return data with that reply.\n\nWaiting for a reply introduces 10-20[ms] of execution time before the function returns an 'ACK'knowledgement.\nBy default, methods *will block* until receiving this acknowledgement unless otherwise specified, like this:\n````python\nbox.move_absolute(x=1000, y=25, wait=False) # will not block.\n````\nThis behavior can only be used for commands to change the Tigerbox state.\nCommands that query the Tigerbox state will always block until they receive a hardware reply.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "a lightweight python interface for ASI brand Tiger Controllers",
"version": "0.0.9",
"split_keywords": [
"driver",
"asi",
"tigercontroller"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e6d12d680e26573d308c9316c09cfe311e560318621de5910427c39712f5ccf",
"md5": "87cb74074c3f23d2ad25679e338fe578",
"sha256": "4078594b7307f3df4b0b761dc76d6e44dc77863a22a2c63f91a74dae7cb92d30"
},
"downloads": -1,
"filename": "TigerASI-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87cb74074c3f23d2ad25679e338fe578",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21547,
"upload_time": "2023-01-31T19:39:04",
"upload_time_iso_8601": "2023-01-31T19:39:04.014010Z",
"url": "https://files.pythonhosted.org/packages/3e/6d/12d680e26573d308c9316c09cfe311e560318621de5910427c39712f5ccf/TigerASI-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d950c29422b7b28056b4c83c3578f482ec3c6247d9b604101339da58baa74fd0",
"md5": "969d201a5bbcacb958e2021cad1f3552",
"sha256": "4ff664e663e37a596f5c0aec4043333aa3f73c49e67fe27649cc27d2e62a2afc"
},
"downloads": -1,
"filename": "TigerASI-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "969d201a5bbcacb958e2021cad1f3552",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 19998,
"upload_time": "2023-01-31T19:39:05",
"upload_time_iso_8601": "2023-01-31T19:39:05.614448Z",
"url": "https://files.pythonhosted.org/packages/d9/50/c29422b7b28056b4c83c3578f482ec3c6247d9b604101339da58baa74fd0/TigerASI-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 19:39:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "AllenNeuralDynamics",
"github_project": "TigerASI",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tigerasi"
}
JSON
