# Axioforce Python SDK
A clean, object-oriented Python wrapper around the Axioforce C API that provides easy-to-use interfaces for device management and data collection.
## Features
- **Simple API**: Clean, Pythonic interface that hides the complexity of the C API
- **Device Management**: Easy device discovery, connection, and control
- **Data Collection**: Flexible data collection with customizable callbacks
- **Simulator Support**: Built-in simulator mode for testing and development
- **Context Manager**: Automatic resource cleanup with `with` statements
- **Type Safety**: Full type hints and dataclass structures
- **Convenience Functions**: Pre-built callbacks for common use cases
## Quick Start
### Basic Usage
```python
from axioforce_sdk import AxioforceSDK
# Create SDK instance
sdk = AxioforceSDK()
# Initialize for real devices
sdk.initialize(log_level="info")
# Or use simulator
sdk.initialize_simulator(csv_file="data.csv", log_level="info")
# Define callbacks
def on_device_discovered(device):
print(f"Found device: {device.name}")
def on_data_received(event):
print(f"Data from {event.device_name}: {event.sensors}")
sdk.on_device_discovered = on_device_discovered
sdk.on_data_received = on_data_received
# Start collecting data
sdk.start_data_collection()
# Stop when done
sdk.shutdown()
```
### Using Context Manager
```python
from axioforce_sdk import AxioforceSDK
# Automatic cleanup with context manager
with AxioforceSDK() as sdk:
sdk.initialize_simulator(log_level="info")
def data_handler(event):
print(f"Received data: {event.timestamp}")
sdk.on_data_received = data_handler
sdk.start_data_collection()
# SDK automatically cleaned up when exiting context
```
## Installation
1. Ensure the Axioforce C API library is available in your system:
- `axioforce_c_api.dll` (Windows)
- `libaxioforce_c_api.dylib` (macOS)
2. Place the `axioforce_sdk.py` file in your project directory or Python path.
3. Import and use the SDK:
```python
from axioforce_sdk import AxioforceSDK
```
## API Reference
### Main Classes
#### `AxioforceSDK`
The main SDK class that provides all functionality.
**Methods:**
- `initialize(log_level="info") -> bool`: Initialize for real hardware devices
- `initialize_simulator(csv_file=None, log_level="info") -> bool`: Initialize for simulator mode
- `start_data_collection(timeout=15.0) -> bool`: Start data collection
- `stop_data_collection()`: Stop data collection
- `shutdown()`: Cleanup resources
- `get_discovered_devices() -> List[DeviceInfo]`: Get list of discovered devices
- `get_event_count() -> int`: Get total number of events received
- `is_data_collection_active() -> bool`: Check if data collection is active
**Properties:**
- `on_device_discovered`: Callback for device discovery events
- `on_data_received`: Callback for data events
#### `DeviceInfo`
Information about a discovered device.
**Fields:**
- `id: str`: Device identifier
- `name: str`: Device name
- `type: str`: Device type
- `state: DeviceState`: Current device state
#### `SensorEvent`
Complete sensor data for a single event.
**Fields:**
- `timestamp: float`: Event timestamp
- `device_name: str`: Name of the device
- `raw_data: List[float]`: Raw sensor values
- `sensors: List[SensorData]`: Processed sensor data
- `model_output: List[List[float]]`: Model output data
#### `SensorData`
Data from a single sensor.
**Fields:**
- `forces: List[float]`: [Fx, Fy, Fz] force values
- `moments: List[float]`: [Mx, My, Mz] moment values
- `cop: List[float]`: [CoPx, CoPy] center of pressure values
- `sensor_id: int`: Sensor identifier
- `raw_values: List[float]`: Raw sensor values
- `name: str`: Sensor name
#### `DeviceState`
Enumeration of device states.
**Values:**
- `CONNECTED`: Device is connected but not running
- `RUNNING`: Device is running and collecting data
- `STOPPED`: Device is stopped
- `ERROR`: Device is in error state
### Convenience Functions
#### `create_csv_collector(output_file, include_header=True)`
Create a callback function that saves data to a CSV file.
```python
from axioforce_sdk import create_csv_collector
csv_callback = create_csv_collector("output.csv", include_header=True)
sdk.on_data_received = csv_callback
```
#### `create_console_printer(print_raw=False, print_sensors=True, print_model=True)`
Create a callback function that prints data to console.
```python
from axioforce_sdk import create_console_printer
printer = create_console_printer(print_sensors=True, print_model=False)
sdk.on_data_received = printer
```
## Examples
### Example 1: Basic Data Collection
```python
from axioforce_sdk import AxioforceSDK
sdk = AxioforceSDK()
try:
# Initialize simulator
sdk.initialize_simulator(log_level="info")
# Set up data handler
def handle_data(event):
if event.sensors:
sensor = event.sensors[0]
print(f"Force: {sensor.forces}, Moment: {sensor.moments}")
sdk.on_data_received = handle_data
# Start collection
if sdk.start_data_collection(timeout=10.0):
print("Collecting data...")
time.sleep(5) # Collect for 5 seconds
print(f"Collected {sdk.get_event_count()} events")
finally:
sdk.shutdown()
```
### Example 2: CSV Output
```python
from axioforce_sdk import AxioforceSDK, create_csv_collector
with AxioforceSDK() as sdk:
sdk.initialize_simulator(log_level="info")
# Create CSV collector
csv_handler = create_csv_collector("sensor_data.csv")
sdk.on_data_received = csv_handler
# Collect data
sdk.start_data_collection(timeout=10.0)
time.sleep(3)
print(f"Data saved to sensor_data.csv")
```
### Example 3: Device Control
```python
from axioforce_sdk import AxioforceSDK, DeviceState
sdk = AxioforceSDK()
try:
sdk.initialize(log_level="info")
# Wait for device discovery
if sdk.start_data_collection(timeout=15.0):
devices = sdk.get_discovered_devices()
for device in devices:
print(f"Device: {device.name} - State: {device.state.name}")
# Stop and restart device
if device.state == DeviceState.RUNNING:
sdk.stop_device(device.name)
time.sleep(1)
sdk.start_device(device.name)
finally:
sdk.shutdown()
```
### Example 4: Custom Data Processing
```python
from axioforce_sdk import AxioforceSDK
# Track statistics
stats = {'total_force': 0.0, 'event_count': 0}
def custom_processor(event):
stats['event_count'] += 1
if event.sensors:
for sensor in event.sensors:
# Calculate force magnitude
force_mag = (sensor.forces[0]**2 + sensor.forces[1]**2 + sensor.forces[2]**2)**0.5
stats['total_force'] += force_mag
with AxioforceSDK() as sdk:
sdk.initialize_simulator(log_level="info")
sdk.on_data_received = custom_processor
sdk.start_data_collection(timeout=10.0)
time.sleep(3)
if stats['event_count'] > 0:
avg_force = stats['total_force'] / stats['event_count']
print(f"Average force: {avg_force:.2f}")
```
## Error Handling
The SDK provides clear error handling:
```python
try:
sdk = AxioforceSDK()
if not sdk.initialize(log_level="info"):
print("Failed to initialize SDK")
return
if not sdk.start_data_collection(timeout=10.0):
print("No devices discovered")
return
# ... use SDK ...
except RuntimeError as e:
print(f"SDK error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
finally:
sdk.shutdown()
```
## Troubleshooting
### Common Issues
1. **Library not found**: Ensure `axioforce_c_api.dll` or `libaxioforce_c_api.dylib` is in the search path
2. **No devices discovered**: Check device connections and drivers
3. **Import errors**: Ensure `axioforce_sdk.py` is in your Python path
### Debug Mode
Enable debug logging for more detailed information:
```python
sdk.initialize(log_level="debug")
```
## License
This SDK is part of the Axioforce project and follows the same licensing terms.
Raw data
{
"_id": null,
"home_page": "https://github.com/axioforce/axioforce-python-sdk",
"name": "axioforce-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Axioforce Team <support@axioforce.com>",
"keywords": "sensor, force, measurement, axioforce, hardware, interface",
"author": "Axioforce Team",
"author_email": "Axioforce Team <support@axioforce.com>",
"download_url": "https://files.pythonhosted.org/packages/5b/1c/5a85e63ab1c93e01d502afa4a879784b39e771660723f4c81f7fcf046f69/axioforce_sdk-1.0.0.tar.gz",
"platform": null,
"description": "# Axioforce Python SDK\n\nA clean, object-oriented Python wrapper around the Axioforce C API that provides easy-to-use interfaces for device management and data collection.\n\n## Features\n\n- **Simple API**: Clean, Pythonic interface that hides the complexity of the C API\n- **Device Management**: Easy device discovery, connection, and control\n- **Data Collection**: Flexible data collection with customizable callbacks\n- **Simulator Support**: Built-in simulator mode for testing and development\n- **Context Manager**: Automatic resource cleanup with `with` statements\n- **Type Safety**: Full type hints and dataclass structures\n- **Convenience Functions**: Pre-built callbacks for common use cases\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom axioforce_sdk import AxioforceSDK\n\n# Create SDK instance\nsdk = AxioforceSDK()\n\n# Initialize for real devices\nsdk.initialize(log_level=\"info\")\n\n# Or use simulator\nsdk.initialize_simulator(csv_file=\"data.csv\", log_level=\"info\")\n\n# Define callbacks\ndef on_device_discovered(device):\n print(f\"Found device: {device.name}\")\n\ndef on_data_received(event):\n print(f\"Data from {event.device_name}: {event.sensors}\")\n\nsdk.on_device_discovered = on_device_discovered\nsdk.on_data_received = on_data_received\n\n# Start collecting data\nsdk.start_data_collection()\n\n# Stop when done\nsdk.shutdown()\n```\n\n### Using Context Manager\n\n```python\nfrom axioforce_sdk import AxioforceSDK\n\n# Automatic cleanup with context manager\nwith AxioforceSDK() as sdk:\n sdk.initialize_simulator(log_level=\"info\")\n \n def data_handler(event):\n print(f\"Received data: {event.timestamp}\")\n \n sdk.on_data_received = data_handler\n sdk.start_data_collection()\n \n # SDK automatically cleaned up when exiting context\n```\n\n## Installation\n\n1. Ensure the Axioforce C API library is available in your system:\n - `axioforce_c_api.dll` (Windows)\n - `libaxioforce_c_api.dylib` (macOS)\n\n2. Place the `axioforce_sdk.py` file in your project directory or Python path.\n\n3. Import and use the SDK:\n ```python\n from axioforce_sdk import AxioforceSDK\n ```\n\n## API Reference\n\n### Main Classes\n\n#### `AxioforceSDK`\n\nThe main SDK class that provides all functionality.\n\n**Methods:**\n\n- `initialize(log_level=\"info\") -> bool`: Initialize for real hardware devices\n- `initialize_simulator(csv_file=None, log_level=\"info\") -> bool`: Initialize for simulator mode\n- `start_data_collection(timeout=15.0) -> bool`: Start data collection\n- `stop_data_collection()`: Stop data collection\n- `shutdown()`: Cleanup resources\n- `get_discovered_devices() -> List[DeviceInfo]`: Get list of discovered devices\n- `get_event_count() -> int`: Get total number of events received\n- `is_data_collection_active() -> bool`: Check if data collection is active\n\n**Properties:**\n\n- `on_device_discovered`: Callback for device discovery events\n- `on_data_received`: Callback for data events\n\n#### `DeviceInfo`\n\nInformation about a discovered device.\n\n**Fields:**\n- `id: str`: Device identifier\n- `name: str`: Device name\n- `type: str`: Device type\n- `state: DeviceState`: Current device state\n\n#### `SensorEvent`\n\nComplete sensor data for a single event.\n\n**Fields:**\n- `timestamp: float`: Event timestamp\n- `device_name: str`: Name of the device\n- `raw_data: List[float]`: Raw sensor values\n- `sensors: List[SensorData]`: Processed sensor data\n- `model_output: List[List[float]]`: Model output data\n\n#### `SensorData`\n\nData from a single sensor.\n\n**Fields:**\n- `forces: List[float]`: [Fx, Fy, Fz] force values\n- `moments: List[float]`: [Mx, My, Mz] moment values\n- `cop: List[float]`: [CoPx, CoPy] center of pressure values\n- `sensor_id: int`: Sensor identifier\n- `raw_values: List[float]`: Raw sensor values\n- `name: str`: Sensor name\n\n#### `DeviceState`\n\nEnumeration of device states.\n\n**Values:**\n- `CONNECTED`: Device is connected but not running\n- `RUNNING`: Device is running and collecting data\n- `STOPPED`: Device is stopped\n- `ERROR`: Device is in error state\n\n### Convenience Functions\n\n#### `create_csv_collector(output_file, include_header=True)`\n\nCreate a callback function that saves data to a CSV file.\n\n```python\nfrom axioforce_sdk import create_csv_collector\n\ncsv_callback = create_csv_collector(\"output.csv\", include_header=True)\nsdk.on_data_received = csv_callback\n```\n\n#### `create_console_printer(print_raw=False, print_sensors=True, print_model=True)`\n\nCreate a callback function that prints data to console.\n\n```python\nfrom axioforce_sdk import create_console_printer\n\nprinter = create_console_printer(print_sensors=True, print_model=False)\nsdk.on_data_received = printer\n```\n\n## Examples\n\n### Example 1: Basic Data Collection\n\n```python\nfrom axioforce_sdk import AxioforceSDK\n\nsdk = AxioforceSDK()\n\ntry:\n # Initialize simulator\n sdk.initialize_simulator(log_level=\"info\")\n \n # Set up data handler\n def handle_data(event):\n if event.sensors:\n sensor = event.sensors[0]\n print(f\"Force: {sensor.forces}, Moment: {sensor.moments}\")\n \n sdk.on_data_received = handle_data\n \n # Start collection\n if sdk.start_data_collection(timeout=10.0):\n print(\"Collecting data...\")\n time.sleep(5) # Collect for 5 seconds\n print(f\"Collected {sdk.get_event_count()} events\")\n \nfinally:\n sdk.shutdown()\n```\n\n### Example 2: CSV Output\n\n```python\nfrom axioforce_sdk import AxioforceSDK, create_csv_collector\n\nwith AxioforceSDK() as sdk:\n sdk.initialize_simulator(log_level=\"info\")\n \n # Create CSV collector\n csv_handler = create_csv_collector(\"sensor_data.csv\")\n sdk.on_data_received = csv_handler\n \n # Collect data\n sdk.start_data_collection(timeout=10.0)\n time.sleep(3)\n \n print(f\"Data saved to sensor_data.csv\")\n```\n\n### Example 3: Device Control\n\n```python\nfrom axioforce_sdk import AxioforceSDK, DeviceState\n\nsdk = AxioforceSDK()\n\ntry:\n sdk.initialize(log_level=\"info\")\n \n # Wait for device discovery\n if sdk.start_data_collection(timeout=15.0):\n devices = sdk.get_discovered_devices()\n \n for device in devices:\n print(f\"Device: {device.name} - State: {device.state.name}\")\n \n # Stop and restart device\n if device.state == DeviceState.RUNNING:\n sdk.stop_device(device.name)\n time.sleep(1)\n sdk.start_device(device.name)\n \nfinally:\n sdk.shutdown()\n```\n\n### Example 4: Custom Data Processing\n\n```python\nfrom axioforce_sdk import AxioforceSDK\n\n# Track statistics\nstats = {'total_force': 0.0, 'event_count': 0}\n\ndef custom_processor(event):\n stats['event_count'] += 1\n \n if event.sensors:\n for sensor in event.sensors:\n # Calculate force magnitude\n force_mag = (sensor.forces[0]**2 + sensor.forces[1]**2 + sensor.forces[2]**2)**0.5\n stats['total_force'] += force_mag\n\nwith AxioforceSDK() as sdk:\n sdk.initialize_simulator(log_level=\"info\")\n sdk.on_data_received = custom_processor\n \n sdk.start_data_collection(timeout=10.0)\n time.sleep(3)\n \n if stats['event_count'] > 0:\n avg_force = stats['total_force'] / stats['event_count']\n print(f\"Average force: {avg_force:.2f}\")\n```\n\n## Error Handling\n\nThe SDK provides clear error handling:\n\n```python\ntry:\n sdk = AxioforceSDK()\n \n if not sdk.initialize(log_level=\"info\"):\n print(\"Failed to initialize SDK\")\n return\n \n if not sdk.start_data_collection(timeout=10.0):\n print(\"No devices discovered\")\n return\n \n # ... use SDK ...\n \nexcept RuntimeError as e:\n print(f\"SDK error: {e}\")\nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\nfinally:\n sdk.shutdown()\n```\n\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Library not found**: Ensure `axioforce_c_api.dll` or `libaxioforce_c_api.dylib` is in the search path\n2. **No devices discovered**: Check device connections and drivers\n3. **Import errors**: Ensure `axioforce_sdk.py` is in your Python path\n\n### Debug Mode\n\nEnable debug logging for more detailed information:\n\n```python\nsdk.initialize(log_level=\"debug\")\n```\n\n## License\n\nThis SDK is part of the Axioforce project and follows the same licensing terms. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Axioforce sensor devices",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/axioforce/axioforce-python-sdk/issues",
"Documentation": "https://github.com/axioforce/axioforce-python-sdk/blob/main/README_SDK.md",
"Homepage": "https://github.com/axioforce/axioforce-python-sdk",
"Repository": "https://github.com/axioforce/axioforce-python-sdk"
},
"split_keywords": [
"sensor",
" force",
" measurement",
" axioforce",
" hardware",
" interface"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8c57a32e07c1720135b3154605af7b347cd4bbba9205b3a90f2a2969830de900",
"md5": "f66ea0b45a782e621ae3573ccf843f27",
"sha256": "b0367cb87fcb6b779692f027d7f953cc5c959ef2a91ec8f7e6e462d4eef893ec"
},
"downloads": -1,
"filename": "axioforce_sdk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f66ea0b45a782e621ae3573ccf843f27",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7701643,
"upload_time": "2025-07-16T23:29:55",
"upload_time_iso_8601": "2025-07-16T23:29:55.416859Z",
"url": "https://files.pythonhosted.org/packages/8c/57/a32e07c1720135b3154605af7b347cd4bbba9205b3a90f2a2969830de900/axioforce_sdk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5b1c5a85e63ab1c93e01d502afa4a879784b39e771660723f4c81f7fcf046f69",
"md5": "05940333276f86d1a9411d7b81230a8e",
"sha256": "5f444025401181c76f88e2122cbd22bae93012f82478b66ede3a0ff00d58408a"
},
"downloads": -1,
"filename": "axioforce_sdk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "05940333276f86d1a9411d7b81230a8e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7630465,
"upload_time": "2025-07-16T23:29:58",
"upload_time_iso_8601": "2025-07-16T23:29:58.397143Z",
"url": "https://files.pythonhosted.org/packages/5b/1c/5a85e63ab1c93e01d502afa4a879784b39e771660723f4c81f7fcf046f69/axioforce_sdk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 23:29:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "axioforce",
"github_project": "axioforce-python-sdk",
"github_not_found": true,
"lcname": "axioforce-sdk"
}
JSON
