sigfox-manager 0.4.0

A Python library for handling Sigfox API operations

Sigfox Manager

A Python library for handling Sigfox API operations with ease.

Features

Currently supports the following operations:

• Get all contracts on current Token
• Get all devices on selected contract
• Get device information
• Get messages from device
• Create device
• List device types with automatic pagination
• Resolve device types by id or name
• Provision devices with input validation

Installation

From PyPI (when published)

pip install sigfox-manager

From Source

git clone https://github.com/Jobenas/sigfox_manager_utility.git
cd sigfox_manager_utility
pip install .

For Development

git clone https://github.com/Jobenas/sigfox_manager_utility.git
cd sigfox_manager_utility
pip install -e .[dev]

Quick Start

from sigfox_manager import SigfoxManager

# Initialize the manager with your Sigfox API credentials
manager = SigfoxManager(user="your_username", pwd="your_password")

# Get all contracts
contracts = manager.get_contracts()
print(f"Found {len(contracts.data)} contracts")

# Get devices for a contract
if contracts.data:
    contract_id = contracts.data[0].id
    devices = manager.get_devices_by_contract(contract_id)
    print(f"Found {len(devices.data)} devices")

# Get device information
if devices.data:
    device_id = devices.data[0].id
    device_info = manager.get_device_info(device_id)
    print(f"Device: {device_info.name}")
    
    # Get device messages
    messages = manager.get_device_messages(device_id)
    print(f"Found {len(messages.data)} messages")
    
    # Paginate through all messages
    all_messages = []
    response = manager.get_device_messages(device_id)
    all_messages.extend(response.data)
    
    while response.paging.next is not None:
        response = manager.get_device_messages(device_id, paging=response.paging)
        all_messages.extend(response.data)
    
    print(f"Total messages retrieved: {len(all_messages)}")

Device Type Management and Provisioning

from sigfox_manager import SigfoxManager

sm = SigfoxManager("API_LOGIN", "API_PASSWORD")

# List all device types with automatic pagination
dts = sm.get_device_types().data
print([(dt.id, dt.name) for dt in dts])

# Provision a device with input validation
# Device type can be specified by id or name
dev = sm.provision_device(
    dev_id="19C3B",
    pac="1234567890ABCDEF",
    dev_type_ref="Type A",  # Can use device type name or id
    name="field-node-42",
    automatic_renewal=True,
)
print(f"Created device: {dev.id} - {dev.name}")

Device Type Management and Provisioning

The library now includes enhanced features for managing device types and provisioning devices with validation:

from sigfox_manager import SigfoxManager

# Initialize the manager
sm = SigfoxManager("API_LOGIN", "API_PASSWORD")

# List all device types
dts = sm.get_device_types().data
print([(dt.id, dt.name) for dt in dts])

# Provision a new device with validation
# - Validates dev_id format (uppercase hex, 3-16 chars)
# - Validates pac format (16 alphanumeric chars)
# - Resolves device type by id or name
dev = sm.provision_device(
    dev_id="19C3B",
    pac="1234567890ABCDEF",
    dev_type_ref="Type A",  # Can be device type id or name
    name="field-node-42",
    automatic_renewal=True,
)
print(dev.id, dev.name)

API Reference

SigfoxManager

The main class for interacting with the Sigfox API.

Constructor

SigfoxManager(user: str, pwd: str)

Methods

• get_contracts(fetch_all_pages: bool = True) -> ContractsResponse: Get all contracts visible to the user
• get_devices_by_contract(contract_id: str, fetch_all_pages: bool = True) -> DevicesResponse: Get all devices for a contract
• get_device_info(device_id: str) -> Device: Get detailed information about a specific device
• get_device_messages(device_id: str, threshold: Optional[int] = None, paging: Optional[Paging] = None) -> DeviceMessagesResponse: Get messages from a device with optional pagination support
• get_device_message_number(device_id: str) -> DeviceMessageStats: Get message metrics for a device
• create_device(dev_id, pac, dev_type_id, name, ...) -> BaseDevice: Create a new device
• get_device_types(fetch_all_pages: bool = True) -> DeviceTypesResponse: Get all device types with pagination support
• resolve_device_type_id(ref: str) -> str: Resolve a device type reference (id or name) to its id
• provision_device(dev_id: str, pac: str, dev_type_ref: str, name: Optional[str] = None, **kwargs) -> BaseDevice: Validate inputs and provision a new device

Exceptions

The library provides custom exceptions for better error handling:

• SigfoxAPIException: Base exception for API errors
• SigfoxDeviceNotFoundError: Raised when a device is not found
• SigfoxAuthError: Raised for authentication errors
• SigfoxDeviceCreateConflictException: Raised when trying to create a duplicate device
• SigfoxDeviceTypeNotFoundException: Raised when a device type cannot be resolved by id or name

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/Jobenas/sigfox_manager_utility.git
cd sigfox_manager_utility

# Install in development mode with dev dependencies
pip install -e .[dev]

Running Tests

pytest tests/

Code Formatting

black sigfox_manager/

Type Checking

mypy sigfox_manager/

Building the Package

python -m build

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

Support

For issues and questions, please use the GitHub Issues page.