Sreethul

Posted on Apr 21

I Built a Python Library for Matrix COSEC Biometric Devices (So You Don’t Have To)

#opensource #python #showdev #api

If you’ve ever worked with COSEC biometric devices, you probably already know…

It’s not as simple as:

“Connect device → Fetch attendance → Done”

In reality, it looks more like:

Confusing APIs
XML responses everywhere
Authentication quirks
Trial-and-error debugging for hours

I ran into all of this while building an HRMS system.

So instead of repeating the same pain in every project, I built a reusable solution:

pycosec

Why I Built This

While working on biometric integration, I expected a clean API experience.

But what I got was:

Raw XML responses
Hard-to-understand response codes
Manual URL construction for every request
Repetitive integration code across projects

At some point, it became clear:

“This shouldn’t be this hard every single time.”

So I created a Python library to simplify everything.

What is pycosec?

pycosec is a lightweight Python package that helps you interact with COSEC biometric devices in a clean and structured way.

It takes care of:

Authentication (Basic Auth)
API communication
XML parsing → Python dictionaries
Response code mapping
Argument validation

So you can focus on your application instead of fighting the device API.

Installation

You can install it directly from PyPI:

https://pypi.org/project/pycosec/

pip install pycosec

Or explore the source code:

https://github.com/KSreethul/pycosec

Real Usage (Based on Actual Implementation)

Here’s a real example based on how the library actually works:

from pycosec import COSECBiometric

# Initialize device connection
device = COSECBiometric(
    machine_ip="192.168.1.100",
    port=80,
    username="admin",
    password="admin123"
)

#  Get basic device configuration
basic_config = device.basic_config()
print("Device Config:", basic_config)


#  Fetch attendance events
events = device.get_attendance_events(
    roll_over_count=0,
    seq_num=1,
    no_of_events=50
)
print("Attendance Events:", events)


#  Create or update a user
response = device.set_cosec_user(
    user_id="EMP001",
    ref_user_id=1,
    name="John Doe",
    user_active=True,
    user_group=1
)
print("User Response:", response)


#  Get user details
user = device.get_cosec_user("EMP001")
print("User Details:", user)


#  Delete user
delete_response = device.delete_cosec_user("EMP001")
print("Delete Response:", delete_response)

Device Configuration Example

You can also configure device settings easily:

# Set device date & time
device.date_and_time_configuration(
    action="set",
    date_dd=21,
    date_mm=4,
    date_yyyy=2026,
    time_hh=15,
    time_mm=30
)

# Configure access settings
device.access_settings_configuration(
    action="set",
    auto_relock=True,
    alarm=True
)

What’s Happening Behind the Scenes?

This is where the library actually saves you a ton of effort:

Automatically builds correct API URLs
Handles authentication headers (Base64 encoded)
Converts XML → Python dictionaries
Filters and parses attendance events
Maps response codes to readable messages
Validates supported arguments before sending requests

Instead of writing all this logic repeatedly, you just call methods.

Real Use Case

I built this while working on an HRMS system where:

Employees check in via biometric devices
Attendance logs need to sync with the backend
The system handles large volumes of data

This library acts as a bridge between COSEC devices and your application.

Before vs After

Before pycosec:

Manual API calls
XML parsing everywhere
Duplicate code in every project
Hard debugging

After pycosec:

Clean Python methods
Faster integration
Reusable code
Easier debugging

Future Improvements

I’m actively working on improving the library. Some ideas:

Async support
More endpoint wrappers
Better error handling
Webhook-based event sync

Contributions Welcome

If you’ve worked with COSEC devices, you know there’s always something new to figure out.

Feel free to:

Open issues
Suggest improvements
Contribute

Let’s make biometric integrations easier for everyone.

Final Thoughts

This library came out of a real problem I faced while building production systems.

It’s not just a wrapper—it’s a way to:

Reduce repetitive work
Simplify integrations
Build faster and cleaner systems

If you’re working with COSEC devices, this might save you hours (or even days).

DEV Community