Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation for python can transport interface #241

Merged
merged 24 commits into from
Nov 2, 2023
Merged

Documentation for python can transport interface #241

Show file tree
Hide file tree
Changes from 23 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
3d7fd90
move examples
mdabrowski1990 Oct 25, 2023
9ae2349
examples added
mdabrowski1990 Oct 25, 2023
6f3d4a0
update CAN segmenter
mdabrowski1990 Oct 25, 2023
bc02972
cosmetic changes
mdabrowski1990 Oct 26, 2023
b9e1cce
Update .readthedocs.yaml
mdabrowski1990 Oct 26, 2023
a6748fd
Update can.rst
mdabrowski1990 Oct 26, 2023
b9ce61c
Update conf.py
mdabrowski1990 Oct 26, 2023
cf36f78
Update .readthedocs.yaml
mdabrowski1990 Oct 26, 2023
33081d7
Update .readthedocs.yaml
mdabrowski1990 Oct 26, 2023
4776594
Update .readthedocs.yaml
mdabrowski1990 Oct 26, 2023
ef18f7d
Update .readthedocs.yaml
mdabrowski1990 Oct 26, 2023
f313385
test build
mdabrowski1990 Oct 27, 2023
f703660
update to features status
mdabrowski1990 Oct 27, 2023
4511590
Update installation.rst
mdabrowski1990 Oct 27, 2023
95c579d
Big update for docs
mdabrowski1990 Oct 31, 2023
b52c219
Update can.rst
mdabrowski1990 Oct 31, 2023
5e25fb4
Update ci.yml
mdabrowski1990 Oct 31, 2023
45d6747
Update conf.py
mdabrowski1990 Oct 31, 2023
06b8f0c
Update segmentation.rst
mdabrowski1990 Oct 31, 2023
386599a
Update pyproject.toml
mdabrowski1990 Oct 31, 2023
dcd443f
OSI Model
mdabrowski1990 Oct 31, 2023
91ca794
Merge branch 'documentation-for-python-can-transport-interface' of ht…
mdabrowski1990 Oct 31, 2023
5e38cad
self-review
mdabrowski1990 Oct 31, 2023
c88c178
Update .readthedocs.yaml
mdabrowski1990 Nov 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ jobs:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ["3.8", "3.9", "3.10", "3.11"]
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]

steps:
- uses: actions/checkout@v4
Expand Down Expand Up @@ -109,7 +109,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11"]
python-version: ["3.8", "3.9", "3.10", "3.11"] # TODO: Add "3.12" when stable

steps:
- uses: actions/checkout@v4
Expand Down Expand Up @@ -138,7 +138,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11"]
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]

steps:
- uses: actions/checkout@v4
Expand Down
10 changes: 9 additions & 1 deletion .readthedocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@
version: 2


# Set the version of Python and other tools you might need
build:
os: ubuntu-22.04
tools:
python: "3.11"
apt_packages:
- graphviz


# Build documentation in the docs/ directory with Sphinx
sphinx:
builder: html
Expand All @@ -17,7 +26,6 @@ formats:

# Optionally set the version of Python and requirements required to build your docs
python:
version: "3.8"
install:
- requirements: docs/requirements_for_docs.txt
- requirements: requirements.txt
15 changes: 10 additions & 5 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Welcome to UDS documentation!
Home <self>
pages/installation.rst
pages/user_guide.rst
pages/examples.rst
autoapi/index.rst
pages/knowledge_base.rst
pages/contribution.rst
Expand Down Expand Up @@ -40,16 +41,20 @@ Current implementation status of package features:
| UDS Messages and Packets | Available since version `0.0.2 |
| | <https://pypi.org/project/py-uds/0.0.2/>`_ |
+----------------------------------------------+--------------------------------------------+
| UDS Packets Reception | Ongoing |
| UDS Packets Reception and Transmission | Available since version `0.3.0 |
| | <https://pypi.org/project/py-uds/0.3.0/>`_ |
+----------------------------------------------+--------------------------------------------+
| UDS Packets Transmission | Planned |
| UDS Messages Reception and Transmission | Planned |
+----------------------------------------------+--------------------------------------------+
| Segmentation | Available since version `0.2.0 |
| Messages Segmentation | Available since version `0.2.0 |
| | <https://pypi.org/project/py-uds/0.2.0/>`_ |
+----------------------------------------------+--------------------------------------------+
| UDS Packets Desegmentation | Available since version `0.2.0 |
| | <https://pypi.org/project/py-uds/0.2.0/>`_ |
+----------------------------------------------+--------------------------------------------+
| Support for Services with multiple responses | Planned |
+----------------------------------------------+--------------------------------------------+
| Client Simulation | Ongoing |
| Client Simulation | Planned |
+----------------------------------------------+--------------------------------------------+
| Server Simulation | Planned |
+----------------------------------------------+--------------------------------------------+
Expand All @@ -64,7 +69,7 @@ Current implementation status of support for communication buses:
+----------+-----------------------+
| Bus | Implementation Status |
+==========+=======================+
| CAN | Ongoing |
| CAN | Partial |
+----------+-----------------------+
| FlexRay | Planned |
+----------+-----------------------+
Expand Down
50 changes: 50 additions & 0 deletions docs/source/pages/examples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
Examples
========
Location of all example files: https://github.com/mdabrowski1990/uds/tree/main/examples


CAN
---
Code examples of UDS protocol communication over CAN bus.

.. seealso:: https://github.com/mdabrowski1990/uds/tree/main/examples/can


.. _example-python-can:

Python-CAN
``````````
Examples with `python-can`_ package being used for controlling CAN bus (handling CAN frames transmission and reception).

.. seealso:: https://github.com/mdabrowski1990/uds/tree/main/examples/can/python-can


Kvaser interface
''''''''''''''''
- Send CAN packets (synchronous implementation):

.. include:: ../../../examples/can/python-can/kvaser/send_packets.py
:code: python

- Send CAN packets (asynchronous implementation):

.. include:: ../../../examples/can/python-can/kvaser/send_packets_asyncio.py
:code: python

- Receive CAN packets (synchronous implementation):

.. include:: ../../../examples/can/python-can/kvaser/receive_packets.py
:code: python

- Receive CAN packets (asynchronous implementation):

.. include:: ../../../examples/can/python-can/kvaser/receive_packets_asyncio.py
:code: python


.. seealso:: https://github.com/mdabrowski1990/uds/tree/main/examples/can/python-can/kvaser


.. _python-can: https://github.com/hardbyte/python-can

.. _Kvaser CAN interfaces: https://www.kvaser.com/products-services/our-products/#/?descriptors=pc_int
22 changes: 18 additions & 4 deletions docs/source/pages/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,27 @@ Installation
.. role:: shell(code)
:language: shell

To install the package, run the following command in your command line interface:
Released versions
-----------------
It is **recommended to use released versions** as they were fully tested and are considered as stable.
UDS package is distributed via `PyPI <https://pypi.org/>`_. All versions and other distribution related details
can be found on https://pypi.org/project/py-uds/ page.

- To install the package, run the following command in your command line interface:

:shell:`pip install py-uds`

If you have already installed the package, you can update it using the following command:
- To update your installation to the newest version of the package, run the following command:

:shell:`pip install -U py-uds`

UDS package is distributed via `PyPI <https://pypi.org/>`_.
You can visit distribution page of UDS package using the following hyperlink: https://pypi.org/project/py-uds/.

Development version
-------------------
For people who likes risk, but looking for features that are currently under the development, the following command
will help with installing the development version of the package that is currently stored on `main` branch of
`github repository <https://github.com/mdabrowski1990/uds>`_:

:shell:`pip install git+https://github.com/mdabrowski1990/uds.git@main`

.. warning:: Use this code on your own responsibility.
84 changes: 42 additions & 42 deletions docs/source/pages/knowledge_base/osi_model.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,48 +51,48 @@ UDS Functionalities
-------------------
An overview of features that are required to fully implement UDS protocol is presented in the table below:

+--------------+-------------------------------------------+----------------------------------------------+
| OSI Layer | Functionalities | Implementation |
+==============+===========================================+==============================================+
| Layer 7 | - diagnostic messages support | - :mod:`uds.message` |
| Application | | |
+--------------+-------------------------------------------+----------------------------------------------+
| Layer 6 | - diagnostic messages data interpretation | *To be provided with Database feature.* |
| Presentation | | |
| | - messaging database import from a file | |
| | | |
| | - messaging database export to a file | |
+--------------+-------------------------------------------+----------------------------------------------+
| Layer 5 | - Client simulation | *To be provided with Client feature.* |
| Session | | |
| | - Server simulation | *To be provided with Server feature.* |
+--------------+-------------------------------------------+----------------------------------------------+
| Layer 4 | - UDS packet support | - :mod:`uds.packet` |
| Transport | | |
| | - bus specific segmentation | - :mod:`uds.segmentation` |
| | | |
| | - bus specific packets transmission | - :mod:`uds.transport_interface` |
| | | |
| | | - :mod:`uds.can` |
| | | |
| | | *Currently under development.* |
+--------------+ | |
| Layer 3 | | *To be extended with support for:* |
| Network | | |
| | | - *Ethernet* |
| | | |
| | | - *LIN* |
| | | |
| | | - *K-Line* |
| | | |
| | | - *FlexRay* |
+--------------+-------------------------------------------+----------------------------------------------+
| Layer 2 | - frames transmission | External python packages for bus handling: |
| Data | | |
+--------------+ - frames receiving | - `CAN <https://python-can.readthedocs.io>`_ |
| Layer 1 | | |
| Physical | | *More packages to be decided.* |
+--------------+-------------------------------------------+----------------------------------------------+
+--------------+-------------------------------------------+-------------------------------------------------------+
| OSI Layer | Functionalities | Implementation |
+==============+===========================================+=======================================================+
| Layer 7 | - diagnostic messages support | - :mod:`uds.message` |
| Application | | |
+--------------+-------------------------------------------+-------------------------------------------------------+
| Layer 6 | - diagnostic messages data interpretation | *To be provided with Database feature.* |
| Presentation | | |
| | - messaging database import from a file | |
| | | |
| | - messaging database export to a file | |
+--------------+-------------------------------------------+-------------------------------------------------------+
| Layer 5 | - Client simulation | *To be provided with Client feature.* |
| Session | | |
| | - Server simulation | *To be provided with Server feature.* |
+--------------+-------------------------------------------+-------------------------------------------------------+
| Layer 4 | - UDS packet support | - :mod:`uds.packet` |
| Transport | | |
| | - bus specific segmentation | - :mod:`uds.segmentation` |
| | | |
| | - bus specific packets transmission | - :mod:`uds.transport_interface` |
| | | |
| | | - :mod:`uds.can` |
| | | |
+--------------+ | *To be extended with support for:* |
| Layer 3 | | |
| Network | | - *Ethernet* |
| | | |
| | | - *LIN* |
| | | |
| | | - *K-Line* |
| | | |
| | | - *FlexRay* |
+--------------+-------------------------------------------+-------------------------------------------------------+
| Layer 2 | - frames transmission | External python packages for bus handling: |
| Data | | |
| | - frames receiving | - CAN: |
+--------------+ | |
| Layer 1 | | - `python-can <https://python-can.readthedocs.io>`_ |
| Physical | | |
| | | *More packages handling other buses to be decided.* |
+--------------+-------------------------------------------+-------------------------------------------------------+

Where:
- OSI Layer - considered OSI Model Layer
Expand Down
6 changes: 3 additions & 3 deletions docs/source/pages/user_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ User Guide
.. toctree::
:caption: Table of Content

user_guide/client_simulation.rst
user_guide/server_simulation.rst
user_guide/message.rst
user_guide/transport.rst
user_guide/segmentation.rst
user_guide/transport.rst
user_guide/client_simulation.rst
user_guide/server_simulation.rst
Loading