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

Update cli doc #373

Merged
merged 1 commit into from
Jun 21, 2019
Merged

Update cli doc #373

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
77 changes: 44 additions & 33 deletions docs/cli.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ Command Line Interface
1. **canconvert**:

converts CAN database formats between all supported formats.

Example: "*canconvert* someArSystemdescription.arxml file.dbc"

2. **cancompare**:
Expand All @@ -17,29 +18,39 @@ Command Line Interface
General
_______

If you properly install canmatrix using *pip,* the setuptools create
two ecxcutables for you: `canconvert` and `cancompare`. You can find these executables
near to your `python(.exe)`

If you aren't able to find the scripts, you can still run it as

::

$ canconvert.py -h
$ canconvert.py --help
$ python -m canmatrix.cli.compare [args]
$ python -m canmatrix.cli.convert [args]

show help message/usage and exits
To show help message/usage call ::

::
$ canconvert -h
$ canconvert --help


Another arguments are ::

$ canconvert.py -v
$ canconvert -v

Output verbosity


::

$ canconvert.py -s
$ canconvert -s

don't print status messages to stdout. (only errors)

::

$ canconvert.py -f FORCE_OUTPUT
$ canconvert -f FORCE_OUTPUT

enforce output format, ignoring output file extension (e.g., -f csv)

Expand All @@ -51,19 +62,19 @@ __________________________

::

$ canconvert.py source.dbc target.xlsx
$ canconvert source.dbc target.xlsx

**convert dbc file to dbf:**

::

$ canconvert.py source.dbc target.dbf
$ canconvert source.dbc target.dbf

**convert arxml file to dbc:**

::

$ canconvert.py source.arxml target.dbc
$ canconvert source.arxml target.dbc

Note: in case of ``.arxml`` there can be multiple can databases in.
Thus the target ``target.dbc`` may in this case be called ``BUS-NAME-IN-ARXML_target.dbc``.
Expand All @@ -75,15 +86,15 @@ You can even convert to the same format:

::

$ canconvert.py source.dbc target.dbc
$ canconvert source.dbc target.dbc

Multiple charset support:

**convert dbc file to dbc with different charset:**

::

$ canconvert.py --dbcImportEncoding=iso-8859-1 --dbcImportCommentEncoding=cp-1252 --dbcExportEncoding=utf-8 --dbcExportCommentEncoding=utf-8 source.dbc target.dbc
$ canconvert --dbcImportEncoding=iso-8859-1 --dbcImportCommentEncoding=cp-1252 --dbcExportEncoding=utf-8 --dbcExportCommentEncoding=utf-8 source.dbc target.dbc

This converts ``source.dbc`` where units are coded in ``iso-8859-1`` and comments are coded in ``cp-1252`` in a ``target.dbc`` where everything is coded in ``utf-8``.
Similar charset conversions are possible or even mandatory for following formats: dbc, dbf and sym.
Expand All @@ -96,31 +107,31 @@ _______________________

::

$ canconvert.py --deleteZeroSignals source.dbc target.dbc
$ canconvert --deleteZeroSignals source.dbc target.dbc

will delete signals with 0 bit length from matrix

**delete unwanted attributes from signals:**

::

$ convert.py --deleteSignalAttributes GenMsgCycleTime,MyAttrib source.dbc target.dbc
$ canconvert --deleteSignalAttributes GenMsgCycleTime,MyAttrib source.dbc target.dbc

will delete the attributes ``GenMsgCycleTime`` and ``MyAttrib`` from all signals in ``source.dbc`` and save the result in ``target.dbc``

**delete unwanted attributes from frames:**

::

$ convert.py --deleteFrameAttributes GenMsgCycleTime,MyAttrib source.dbc target.dbc
$ canconvert --deleteFrameAttributes GenMsgCycleTime,MyAttrib source.dbc target.dbc

will delete the attributes ``GenMsgCycleTime`` and ``MyAttrib`` from all frames in ``source.dbc`` and save the result in ``target.dbc``

**recalculate DLC:**

::

$ canconvert.py --recalcDLC=max source.dbc target.dbc
$ canconvert --recalcDLC=max source.dbc target.dbc

this will recalculate DLC for each frame in ``source.dbc``.
In ``target.dlc`` the same DLC like in ``source.dbc`` will be stored, except the calculated DLC is bigger.
Expand All @@ -130,7 +141,7 @@ Than the calculated DLC will be stored.

::

$ canconvert.py --recalcDLC=force source.dbc target.dbc
$ canconvert --recalcDLC=force source.dbc target.dbc

this will recalculate DLC for each frame in ``source.dbc``.
In ``target.dlc`` the calculated DLC will be stored independently from ``source.dbc``.
Expand All @@ -139,23 +150,23 @@ In ``target.dlc`` the calculated DLC will be stored independently from ``source.

::

$ canconvert.py --deleteObsoleteDefines source.dbc target.dbc
$ canconvert --deleteObsoleteDefines source.dbc target.dbc

this will remove all defines which no attribute exist for in ``source.dbc`` and store the result in ``target.dlc``.

**delete ECU:**

::

$ canconvert.py --deleteECU=myEcu,myEcu2 source.dbc target.dbc
$ canconvert --deleteECU=myEcu,myEcu2 source.dbc target.dbc

this will remove ECUs ``myEcu`` and ``myEcu2`` in ``source.dbc`` and store the result in ``target.dlc``.

**rename ECU:**

::

$ canconvert.py --renameECU=myEcu:myNewEcu,myEcu2:myNewEcu2 source.dbc target.dbc
$ canconvert --renameECU=myEcu:myNewEcu,myEcu2:myNewEcu2 source.dbc target.dbc

this will load ``source.dbc`` and rename ECU ``myEcu`` in ``myNewEcu`` and ``myEcu2`` in ``myNewEcu2``.
The result is stored in ``target.dlc``.
Expand All @@ -164,15 +175,15 @@ The result is stored in ``target.dlc``.

::

$ canconvert.py --deleteFrame=myFrame,myFrame2 source.dbc target.dbc
$ canconvert --deleteFrame=myFrame,myFrame2 source.dbc target.dbc

this will remove frames ``myFrame`` and ``myFrame2`` in ``source.dbc`` and store the result in ``target.dlc``.

**rename Frame:**

::

$ canconvert.py --renameFrame=myFrame:myNewFrame,myFrame2:myNewFrame2 source.dbc target.dbc
$ canconvert --renameFrame=myFrame:myNewFrame,myFrame2:myNewFrame2 source.dbc target.dbc

this will load ``source.dbc`` and rename frames ``myFrame`` in ``myNewFrame`` and ``myFrame2`` in ``myNewFrame2``.
The result is stored in ``target.dlc``.
Expand All @@ -182,15 +193,15 @@ The result is stored in ``target.dlc``.

::

$ canconvert.py --deleteSignal=mySignal,mySignal2 source.dbc target.dbc
$ canconvert --deleteSignal=mySignal,mySignal2 source.dbc target.dbc

this will remove signales ``mySignal`` and ``mySignal2`` in ``source.dbc`` and store the result in ``target.dlc``.

**rename Signal:**

::

$ canconvert.py --renameSignal=mySignal:myNewSignal,mySignal2:myNewSignal2 source.dbc target.dbc
$ canconvert --renameSignal=mySignal:myNewSignal,mySignal2:myNewSignal2 source.dbc target.dbc

this will load ``source.dbc`` and rename signals ``mySignal`` in ``myNewSignal`` and ``mySignal2`` in ``myNewSignal2``.
The result is stored in ``target.dlc``.
Expand All @@ -199,14 +210,14 @@ The result is stored in ``target.dlc``.

::

$ canconvert.py --setFrameFd=myFrame,myFrame2 source.dbc target.dbc
$ canconvert --setFrameFd=myFrame,myFrame2 source.dbc target.dbc

this will set frame-type of ``myFrame`` and ``myFrame2`` in ``source.dbc`` to CANFD and store the result in ``target.dlc``
list) Syntax: --setFrameFd=myFrame1,mySecondFrame

::

$ canconvert.py --unsetFrameFd=myFrame,myFrame2 source.dbc target.dbc
$ canconvert --unsetFrameFd=myFrame,myFrame2 source.dbc target.dbc

this will set frame-type of ``myFrame`` and ``myFrame2`` in ``source.dbc`` to normal (not FD) and store the result in ``target.dlc``
list) Syntax: --unsetFrameFd=myFrame1,mySecondFrame
Expand All @@ -219,7 +230,7 @@ __________________

::

$ canconvert.py --ecus=REAR_ECU source.dbc target.dbc
$ canconvert --ecus=REAR_ECU source.dbc target.dbc

This generates a ``target.dbc`` with all Informations out of ``source.dbc`` which are needed for ``REAR_ECU``.
All frames which are received or sent by ``REAR_ECU`` are extracted. Also all attributes of the frames and the ECU.
Expand All @@ -229,45 +240,45 @@ This is some *lite* ECU-Extract.

::

$ canconvert.py --ecus=FRONT_ECU,REAR_ECU source.dbc target.dbc
$ canconvert --ecus=FRONT_ECU,REAR_ECU source.dbc target.dbc

**extract frame[s] out of matrix:**

::

$ canconvert.py --frames=REAR_FRAME,FRONT_FRAME source.dbc target.dbc
$ canconvert --frames=REAR_FRAME,FRONT_FRAME source.dbc target.dbc

Extracts the frames ``REAR_FRAME`` and ``FRONT_FRAME`` with the needed ECUs and attributes.

**merge multiple databases:**

::

$ canconvert.py --merge=second.dbc source.dbc target.dbc
$ canconvert --merge=second.dbc source.dbc target.dbc

Merges ``source.dbc`` and ``second.dbc`` in ``target.dbc``.

**merge ECU from other database:**

::

$ canconvert.py --merge=second.dbc:ecu=REAR_ECU source.dbc target.dbc
$ canconvert --merge=second.dbc:ecu=REAR_ECU source.dbc target.dbc

Merges REAR_ECU out of ``second.dbc`` with ``source.dbc`` and store result in ``target.dbc``.

**merge FRAME from other database:**

::

$ canconvert.py --merge=second.dbc:frame=REAR_FRAME source.dbc target.dbc
$ canconvert --merge=second.dbc:frame=REAR_FRAME source.dbc target.dbc

Merges REAR_FRAME out of ``second.dbc`` with ``source.dbc`` and store result in ``target.dbc``.

**combinations and multiple extraction possible:**

::

$ canconvert.py --merge=second.dbc:ecu=REAR_ECU:ecu=FRONT_ECU:frame=FRAME1:FRAME=FRAME2 source.dbc target.dbc
$ canconvert --merge=second.dbc:ecu=REAR_ECU:ecu=FRONT_ECU:frame=FRAME1:FRAME=FRAME2 source.dbc target.dbc

Merges REAR_ECU and FRONT_ECU and FRAME1 and FRAME2 out of ``second.dbc`` with ``source.dbc`` and store result in ``target.dbc``.

Expand Down