WinUsbCDC

Name	WinUsbCDC JSON
Version	1.7 JSON
	download
home_page	https://gitlab.com/alelec/winusbcdc
Summary	Python package for communicating with USB / CDC devices on windows via the WinUsb driver
upload_time	2023-08-08 00:32:35
maintainer
docs_url	None
author	Andrew Leech
requires_python
license	MIT
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            WinUsbCDC
=========

WinUsbCDC is a python package for communicating with USB / CDC devices
on windows via the built-in
`WinUsb <https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb-installation>`__
driver.

It's intended for communicating with USB CDC (virtual com port) devices
on windows without using the built in usbserial.sys driver as it is
rather unstable and has data loss issues on Win 10 -
https://wiki.segger.com/CDC#CDC-ACM\_issues\_on\_Windows\_10 -
https://community.nxp.com/thread/458640 -
https://social.msdn.microsoft.com/Forums/sqlserver/en-US/671638cd-0aed-4cae-80f2-860c1c551347/usb-cdc-acm-data-lost?forum=wdk

The standard means of usage is via the
``winusbcdc.ComPort(name, vid, pid)`` class which roughly matches the
``pyserial.Serial`` class api.

This module is based directly on
`WinUsbPy <https://github.com/felHR85/WinUsbPy>`__ and as such also
exposes the same WinUSB api: - A 1:1 wrapper over WinUsb which allows
calling C++ functions directly from involved dlls. - A high level api
which simplifies a lot of C++/windll/ctypes messy interactions offering
just a bunch of easy methods.

Install WinUsbCDC
=================

::

    pip install winusbcdc

::

    python setup.py install

USB CDC Device
==============

Ensure your device has the WinUSB driver configured. This can be done
with `Zadig <https://zadig.akeo.ie/>`__, `libusbk
InfWizard <https://osdn.net/projects/sfnet_libusb-win32/downloads/libusb-win32-releases/libusbK-inf-wizard.exe/>`__
or similar.

.. code:: python

    from winusbcdc import ComPort
    p = ComPort("My USB Device")  # friendly name as shown in device manager 
    # or 
    p = ComPort(vid=0xF055, pid=0x9800)

    p.open()
    p.write(b'foo')
    print(p.read())
    p.close()

Low Level WinUsbPy Api
======================

Low level api offers three methods for invoking functions from three
different dlls.

.. code:: python

    #args: arguments of the C++ function called
    def exec_function_winusb(self, function_name, *args):
    def exec_function_kernel32(self, function_name, *args):
    def exec_function_setupapi(self, function_name, *args):

if we need to call
`SetupDiGetClassDevs <http://msdn.microsoft.com/en-us/library/windows/hardware/ff551069%28v=vs.85%29.aspx>`__
which presents this prototype:

``c++ HDEVINFO SetupDiGetClassDevs(_In_opt_ const GUID *ClassGuid,_In_opt_ PCTSTR Enumerator,_In_opt_ HWND hwndParent,_In_ DWORD Flags);``

.. code:: python

    from winusbpy import *
    from ctypes import *
    from ctypes.wintypes import *
    from winusbclasses import DIGCF_DEVICE_INTERFACE, DIGCF_PRESENT

    api = WinUSBApi()
    byte_array = c_byte * 8
    guid = GUID(0xA5DCBF10L, 0x6530, 0x11D2, byte_array(0x90, 0x1F, 0x00, 0xC0, 0x4F, 0xB9, 0x51, 0xED))
    flags = DWORD(DIGCF_DEVICE_INTERFACE | DIGCF_PRESENT)

    hdev_info = api.exec_function_setupapi("SetupDiGetClassDevs", byref(guid), None, None, flags)

`Good resources of WinUsb if you develop using this low level
layer <http://msdn.microsoft.com/en-us/library/windows/hardware/ff540174(v=vs.85).aspx>`__

High Level WinUsbPy Api
=======================

Built on top of the low level wrapper is a more usable api to perform
common USB operations. Here it is list of defined functions:

.. code:: python

    # Possible keyword arguments: default, present, allclasses, profile, deviceinterface (Boolean), Usually called as follows list_usb_devices(deviceinterface=True, present=True)
    def list_usb_devices(self, **kwargs):

    # vid and pid must be str, returns True if device was correctly initialized and False otherwise
    def init_winusb_device(self, vid, pid): 

    # path must be str, returns True if device was correctly initialized and False otherwise
    # example init_winusb_device_with_path("\\\\?\\usb#vid_9999&pid_0102#3555303335351909000b0#{a5dcbf10-6530-11d2-901f-00c04fb951ed}")
    def init_winusb_device_with_path(self, path): 

    # Returns True if device was correctly closed and False otherwise.
    def close_winusb_device(self):

    # Returns last error code. See http://msdn.microsoft.com/en-us/library/windows/desktop/ms681382%28v=vs.85%29.aspx
    def get_last_error_code(self):

    # Returns information for a open device (0x03:High Speed, 0x01:full-speed or lower), query=1 in order to get USB speed.
    def query_device_info(self, query=1):

    # Returns a UsbInterfaceDescriptor object with information about a specified interface
    def query_interface_settings(self, index):

    # Change current interface, Winusb opens first interface (0 index) when a device is initialized
    def change_interface(self, index):

    # Returns a PipeInfo object with information of a specified pipe within current interface
    def query_pipe(self, pipe_index):

    # Send a control requesto to open device, setup_packet is a UsbSetupPacket object.
    # buff = None implies no data is going to be transferred besides setup packet
    # buff = [0] create a buffer of length 1. Buffer could be IN or OUT, direction is defined in setup packet
    # it returns a dict with the response and with the buffer under the keywords 'result' and 'buffer'
    def control_transfer(self, setup_packet, buff=None):

    #Send Bulk data to the Usb device, write_buffer must be a str buffer
    def write(self, pipe_id, write_buffer):

    #Read Bulk data from the Usb device, Returns of a buffer not greater than length_buffer length
    def read(self, pipe_id, length_buffer):

Let's say hello to our device:

.. code:: python

    from winusbpy import *
    vid = "vid_device" # for example: VID:067b PID:2303
    pid = "pid_device"

    api = WinUsbPy()
    result = api.list_usb_devices(deviceinterface=True, present=True)
    if result:
      if api.init_winusb_device(pl2303_vid, pl2303_pid):
        api.write(0x02, "hello")

Real examples
=============

If you run winusbcdc as a module it should act like a basic serial
terminal, see ``__main__.py`` for the code used.

::

    python -m winusbcdc --name "My USB Device"


In "Examples" folder there are two WinUsbPy examples configuring a PL2303
serial usb device, listing characteristics and sending data.

`Using WinUsbPy Low Level
Api <https://github.com/felHR85/WinUsbPy/blob/master/winusbpy/examples/winusbtest.py>`__

`Using WinUsbPy High Level
Api <https://github.com/felHR85/WinUsbPy/blob/master/winusbpy/examples/winusbtest2.py>`__



version: 1.7

            

Raw data

            {
    "_id": null,
    "home_page": "https://gitlab.com/alelec/winusbcdc",
    "name": "WinUsbCDC",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Andrew Leech",
    "author_email": "andrew@alelec.net",
    "download_url": "",
    "platform": null,
    "description": "WinUsbCDC\n=========\n\nWinUsbCDC is a python package for communicating with USB / CDC devices\non windows via the built-in\n`WinUsb <https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb-installation>`__\ndriver.\n\nIt's intended for communicating with USB CDC (virtual com port) devices\non windows without using the built in usbserial.sys driver as it is\nrather unstable and has data loss issues on Win 10 -\nhttps://wiki.segger.com/CDC#CDC-ACM\\_issues\\_on\\_Windows\\_10 -\nhttps://community.nxp.com/thread/458640 -\nhttps://social.msdn.microsoft.com/Forums/sqlserver/en-US/671638cd-0aed-4cae-80f2-860c1c551347/usb-cdc-acm-data-lost?forum=wdk\n\nThe standard means of usage is via the\n``winusbcdc.ComPort(name, vid, pid)`` class which roughly matches the\n``pyserial.Serial`` class api.\n\nThis module is based directly on\n`WinUsbPy <https://github.com/felHR85/WinUsbPy>`__ and as such also\nexposes the same WinUSB api: - A 1:1 wrapper over WinUsb which allows\ncalling C++ functions directly from involved dlls. - A high level api\nwhich simplifies a lot of C++/windll/ctypes messy interactions offering\njust a bunch of easy methods.\n\nInstall WinUsbCDC\n=================\n\n::\n\n    pip install winusbcdc\n\n::\n\n    python setup.py install\n\nUSB CDC Device\n==============\n\nEnsure your device has the WinUSB driver configured. This can be done\nwith `Zadig <https://zadig.akeo.ie/>`__, `libusbk\nInfWizard <https://osdn.net/projects/sfnet_libusb-win32/downloads/libusb-win32-releases/libusbK-inf-wizard.exe/>`__\nor similar.\n\n.. code:: python\n\n    from winusbcdc import ComPort\n    p = ComPort(\"My USB Device\")  # friendly name as shown in device manager \n    # or \n    p = ComPort(vid=0xF055, pid=0x9800)\n\n    p.open()\n    p.write(b'foo')\n    print(p.read())\n    p.close()\n\nLow Level WinUsbPy Api\n======================\n\nLow level api offers three methods for invoking functions from three\ndifferent dlls.\n\n.. code:: python\n\n    #args: arguments of the C++ function called\n    def exec_function_winusb(self, function_name, *args):\n    def exec_function_kernel32(self, function_name, *args):\n    def exec_function_setupapi(self, function_name, *args):\n\nif we need to call\n`SetupDiGetClassDevs <http://msdn.microsoft.com/en-us/library/windows/hardware/ff551069%28v=vs.85%29.aspx>`__\nwhich presents this prototype:\n\n``c++ HDEVINFO SetupDiGetClassDevs(_In_opt_ const GUID *ClassGuid,_In_opt_ PCTSTR Enumerator,_In_opt_ HWND hwndParent,_In_ DWORD Flags);``\n\n.. code:: python\n\n    from winusbpy import *\n    from ctypes import *\n    from ctypes.wintypes import *\n    from winusbclasses import DIGCF_DEVICE_INTERFACE, DIGCF_PRESENT\n\n    api = WinUSBApi()\n    byte_array = c_byte * 8\n    guid = GUID(0xA5DCBF10L, 0x6530, 0x11D2, byte_array(0x90, 0x1F, 0x00, 0xC0, 0x4F, 0xB9, 0x51, 0xED))\n    flags = DWORD(DIGCF_DEVICE_INTERFACE | DIGCF_PRESENT)\n\n    hdev_info = api.exec_function_setupapi(\"SetupDiGetClassDevs\", byref(guid), None, None, flags)\n\n`Good resources of WinUsb if you develop using this low level\nlayer <http://msdn.microsoft.com/en-us/library/windows/hardware/ff540174(v=vs.85).aspx>`__\n\nHigh Level WinUsbPy Api\n=======================\n\nBuilt on top of the low level wrapper is a more usable api to perform\ncommon USB operations. Here it is list of defined functions:\n\n.. code:: python\n\n    # Possible keyword arguments: default, present, allclasses, profile, deviceinterface (Boolean), Usually called as follows list_usb_devices(deviceinterface=True, present=True)\n    def list_usb_devices(self, **kwargs):\n\n    # vid and pid must be str, returns True if device was correctly initialized and False otherwise\n    def init_winusb_device(self, vid, pid): \n\n    # path must be str, returns True if device was correctly initialized and False otherwise\n    # example init_winusb_device_with_path(\"\\\\\\\\?\\\\usb#vid_9999&pid_0102#3555303335351909000b0#{a5dcbf10-6530-11d2-901f-00c04fb951ed}\")\n    def init_winusb_device_with_path(self, path): \n\n    # Returns True if device was correctly closed and False otherwise.\n    def close_winusb_device(self):\n\n    # Returns last error code. See http://msdn.microsoft.com/en-us/library/windows/desktop/ms681382%28v=vs.85%29.aspx\n    def get_last_error_code(self):\n\n    # Returns information for a open device (0x03:High Speed, 0x01:full-speed or lower), query=1 in order to get USB speed.\n    def query_device_info(self, query=1):\n\n    # Returns a UsbInterfaceDescriptor object with information about a specified interface\n    def query_interface_settings(self, index):\n\n    # Change current interface, Winusb opens first interface (0 index) when a device is initialized\n    def change_interface(self, index):\n\n    # Returns a PipeInfo object with information of a specified pipe within current interface\n    def query_pipe(self, pipe_index):\n\n    # Send a control requesto to open device, setup_packet is a UsbSetupPacket object.\n    # buff = None implies no data is going to be transferred besides setup packet\n    # buff = [0] create a buffer of length 1. Buffer could be IN or OUT, direction is defined in setup packet\n    # it returns a dict with the response and with the buffer under the keywords 'result' and 'buffer'\n    def control_transfer(self, setup_packet, buff=None):\n\n    #Send Bulk data to the Usb device, write_buffer must be a str buffer\n    def write(self, pipe_id, write_buffer):\n\n    #Read Bulk data from the Usb device, Returns of a buffer not greater than length_buffer length\n    def read(self, pipe_id, length_buffer):\n\nLet's say hello to our device:\n\n.. code:: python\n\n    from winusbpy import *\n    vid = \"vid_device\" # for example: VID:067b PID:2303\n    pid = \"pid_device\"\n\n    api = WinUsbPy()\n    result = api.list_usb_devices(deviceinterface=True, present=True)\n    if result:\n      if api.init_winusb_device(pl2303_vid, pl2303_pid):\n        api.write(0x02, \"hello\")\n\nReal examples\n=============\n\nIf you run winusbcdc as a module it should act like a basic serial\nterminal, see ``__main__.py`` for the code used.\n\n::\n\n    python -m winusbcdc --name \"My USB Device\"\n\n\nIn \"Examples\" folder there are two WinUsbPy examples configuring a PL2303\nserial usb device, listing characteristics and sending data.\n\n`Using WinUsbPy Low Level\nApi <https://github.com/felHR85/WinUsbPy/blob/master/winusbpy/examples/winusbtest.py>`__\n\n`Using WinUsbPy High Level\nApi <https://github.com/felHR85/WinUsbPy/blob/master/winusbpy/examples/winusbtest2.py>`__\n\n\n\nversion: 1.7\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Python package for communicating with USB / CDC devices on windows via the WinUsb driver",
    "version": "1.7",
    "project_urls": {
        "Homepage": "https://gitlab.com/alelec/winusbcdc"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "777c9b71cb53ee8b5970ba0d527882daa5f33d1654f3039e4717e0ad6dec2af3",
                "md5": "fcd8e02d8a1646508f3f5cf9acde4761",
                "sha256": "ab0c58bed7667daf9593168562a8aa7e6265c17bf15d2dc77e8d7096576fd661"
            },
            "downloads": -1,
            "filename": "WinUsbCDC-1.7-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "fcd8e02d8a1646508f3f5cf9acde4761",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 19200,
            "upload_time": "2023-08-08T00:32:35",
            "upload_time_iso_8601": "2023-08-08T00:32:35.371739Z",
            "url": "https://files.pythonhosted.org/packages/77/7c/9b71cb53ee8b5970ba0d527882daa5f33d1654f3039e4717e0ad6dec2af3/WinUsbCDC-1.7-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-08-08 00:32:35",
    "github": false,
    "gitlab": true,
    "bitbucket": false,
    "codeberg": false,
    "gitlab_user": "alelec",
    "gitlab_project": "winusbcdc",
    "lcname": "winusbcdc"
}