Enhance OpenSIPS Integration with New Python Package

In today’s world of integrated services, the ability of OpenSIPS to interface with external applications is no longer optional – it’s a necessity. And to meet this necessity, we have released a new Python package – a “Swiss army knife” tool to provide a simpler, faster and more efficient way to integrate with OpenSIPS.

This package facilitates efficient two-way communication by providing Python modules to:

• Run commands: Send commands effortlessly over the Management Interface (MI) and get the response back – opensips.mi module.
• Event Handling: Receive and process real-time events via the Event Interface (EVI) – opensips.event module

It additionally includes the following powerful command-line tools:

• opensips-mi: A tool designed to execute MI commands. It displays the output directly in the console. It serves as a simplified alternative to opensips-cli -x mi command.
• opensips-event: A utility that registers for specific events and outputs them directly to the console. Ideal for testing event generation in various scenarios with ease.

opensips.mi

This module can be used to send commands to the OpenSIPS MI Interface. It currently supports three different transport protocols:

• fifo: used to run commands locally, on the same machine OpenSIPS runs.
• datagram: used to run commands over datagram messages.
• http: runs commands over HTTP queries.

Of course, it is essential to ensure that OpenSIPS has the appropriate MI module loaded. It must also be properly configured for external usage.

The module returns command responses in the form of a JSON object, allowing for seamless further processing as required.

opensips.event

This module registers with OpenSIPS for a specific event. It receives notifications over the datagram transport when the event is triggered. It can optionally include an expiration timeout. A designated function is invoked for each event that occurs. The event payload is delivered as a JSON object, containing all relevant information associated with the event.

The module provides back-ends for synchronous waiting for events in a separate thread. It also uses the asyncio interface for asynchronous handling of I/O events.

Examples

The simplest way to make use of this package is to use the opensips-mi tool to run arbitrary commands to OpenSIPS MI:

$ opensips-mi uptime
{
    "Now": "Wed Nov 20 10:40:23 2024",
    "Up since": "Wed Nov 20 10:37:52 2024",
    "Up time": "151 [sec]"
}

This command gets the output print at console as JSON – you can grab it and process it accordingly (i.e. using jq). However, you can do this programmatically as well, just as easy, using the following script:

$ python -c 'import opensips.mi; print(opensips.mi.OpenSIPSMI().execute("uptime"))'
OrderedDict({'Now': 'Wed Nov 20 10:44:34 2024', 'Up since': 'Wed Nov 20 10:37:52 2024', 'Up time': '402 [sec]'}

The latest version, of course, offers enhanced flexibility in both constructing the command and processing the response. You can find advanced usage examples in the following section.

Handling events through the OpenSIPS python package is quite simple as well: if you just want to test the generation/receipt of the events, you can easily use the opensips-event command:

$ opensips-event E_TEST
{
    "jsonrpc": "2.0",
    "method": "E_TEST",
    "params": {
        "attempt": 0
    }
}

The same behavior can be obtained programmatically using the following script:

import time
from opensips.mi import OpenSIPSMI, OpenSIPSMIException
from opensips.event import OpenSIPSEvent, OpenSIPSEventHandler

mi_connector = OpenSIPSMI()
hdl = OpenSIPSEventHandler()
event = hdl.subscribe('E_TEST', print)
time.sleep(3600)
event.unsubscribe('E_TEST')

Running this script results in:

$ python3 opensips-event.py
OrderedDict({'jsonrpc': '2.0', 'method': 'E_TEST', 'params': OrderedDict({'attempt': 0})})

Projects

There are already a bunch of projects using the OpenSIPS Python package:

• OpenSIPS CLI has been migrated to use this package for running MI commands
• SIPSSert – provides a task for running MI commands
• OpenSIPS SIPSSert tests – uses the opensips.mi module to run commands to check OpenSIPS status for its tests
• OpenSIPS AI Voice Connector Community Edition – uses both python module for the interaction with OpenSIPS B2B UA instance.

Distribution

The package is available through multiple distribution channels:

• OpenSIPS Official Repositories for Debian and Redhat/Centos as python3-opensips package in the cli-nightly repository
• PyPi Python repository as the opensips module
• Docker python-opensips image for quickly running commands
• GitHub releases

Conclusions

The python-opensips module is a valuable tool for developers. It allows them to leverage Python’s simplicity and versatility in their OpenSIPS-based telecommunication projects.

This project has already been integrated in various other tools. Feel free to give it a try yourself and share your thoughts with us!