1.. _external_module_cannectivity:
2
3CANnectivity USB to CAN adapter firmware
4########################################
5
6Introduction
7************
8
9`CANnectivity`_ is an open source firmware for Universal Serial Bus (USB) to Controller Area Network
10(CAN) adapters.
11
12The firmware implements the Geschwister Schneider USB/CAN device protocol (often referred to as
13"gs_usb"). This protocol is supported by the Linux kernel SocketCAN `gs_usb driver`_, by
14`python-can`_, and by many other software packages.
15
16The firmware, which is based on Zephyr RTOS, allows turning your favorite microcontroller
17development board into a full-fledged USB to CAN adapter.
18
19CANnectivity is licensed under the Apache-2.0 license.
20
21Usage with Zephyr
22*****************
23
24The CANnectivity firmware repository is a Zephyr :ref:`module <modules>` which allows for reuse of
25its components (i.e. the "gs_usb" protocol implementation) outside of the CANnectivity firmware
26application.
27
28To pull in CANnectivity as a Zephyr module, either add it as a West project in the ``west.yaml``
29file or pull it in by adding a submanifest (e.g. ``zephyr/submanifests/cannectivity.yaml``) file
30with the following content and run ``west update``:
31
32.. code-block:: yaml
33
34   manifest:
35     projects:
36       - name: cannectivity
37         url: https://github.com/CANnectivity/cannectivity.git
38         revision: main
39         path: custom/cannectivity # adjust the path as needed
40
41Once CANnectivity is added as a Zephyr module, the "gs_usb" implementation can be reused outside of
42the CANnectivity firmware application by including its header:
43
44.. code-block:: c
45
46   #include <cannectivity/usb/class/gs_usb.h>
47
48Please see the header file for the API details.
49
50.. _CANnectivity:
51   https://github.com/CANnectivity/cannectivity
52
53.. _gs_usb driver:
54   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/net/can/usb/gs_usb.c
55
56.. _python-can:
57   https://python-can.readthedocs.io/en/stable/interfaces/gs_usb.html
58