mirror of
https://github.com/intrepidcs/libicsneo.git
synced 2026-08-05 01:18:36 +02:00
Docs: Refactor
This commit is contained in:
Kyle Schwarz
+19
-171
@@ -1,188 +1,36 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# NOTE: The conf.py file is automatically updated by CMake when there are
|
||||
# changes to the version. Update the conf.py.template and then build to
|
||||
# propagate changes here. This file should be committed so that
|
||||
# ReadTheDocs can use it.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
import os
|
||||
import subprocess
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
subprocess.call('cd ..; doxygen docs/icsneocpp/Doxyfile', shell=True)
|
||||
subprocess.call('cd ..; doxygen docs/icsneoc/Doxyfile', shell=True)
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['sphinx.ext.imgmath', 'sphinx.ext.todo', 'breathe' ]
|
||||
|
||||
breathe_projects = { "libicsneo": "build/doxygen/xml" }
|
||||
breathe_default_project = "libicsneo"
|
||||
|
||||
try:
|
||||
os.makedirs('build/sphinx')
|
||||
except FileExistsError:
|
||||
pass
|
||||
try:
|
||||
os.makedirs('build/doxygen')
|
||||
except FileExistsError:
|
||||
pass
|
||||
|
||||
subprocess.call('cd ..; doxygen docs/Doxyfile', shell=True)
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = 'libicsneo'
|
||||
copyright = '2018-2024, Intrepid Control Systems, Inc.'
|
||||
copyright = '2024, Intrepid Control Systems, Inc.'
|
||||
author = 'Intrepid Control Systems, Inc.'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '0.2.0'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '0.2.0 '
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
extensions = ['breathe', 'sphinx.ext.autodoc']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This patterns also effect to html_static_path and html_extra_path
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
breathe_projects = {
|
||||
'icsneocpp': 'icsneocpp/doxygen/xml',
|
||||
'icsneoc': 'icsneoc/doxygen/xml',
|
||||
}
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
breathe_default_project = 'icsneocpp'
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
html_theme_options = {
|
||||
|
||||
}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# This is required for the alabaster theme
|
||||
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
|
||||
html_sidebars = {
|
||||
'**': [
|
||||
'relations.html', # needs 'show_related': True theme option to display
|
||||
'searchbox.html',
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'libicsneodoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'libicsneo.tex', 'libicsneo Documentation',
|
||||
'Intrepid Control Systems, Inc.', 'manual'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'libicsneo', 'libicsneo Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'libicsneo', 'libicsneo Documentation',
|
||||
author, 'libicsneo', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,188 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# NOTE: The conf.py file is automatically updated by CMake when there are
|
||||
# changes to the version. Update the conf.py.template and then build to
|
||||
# propagate changes here. This file should be committed so that
|
||||
# ReadTheDocs can use it.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
import os
|
||||
import subprocess
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['sphinx.ext.imgmath', 'sphinx.ext.todo', 'breathe' ]
|
||||
|
||||
breathe_projects = { "libicsneo": "build/doxygen/xml" }
|
||||
breathe_default_project = "libicsneo"
|
||||
|
||||
try:
|
||||
os.makedirs('build/sphinx')
|
||||
except FileExistsError:
|
||||
pass
|
||||
try:
|
||||
os.makedirs('build/doxygen')
|
||||
except FileExistsError:
|
||||
pass
|
||||
|
||||
subprocess.call('cd ..; doxygen docs/Doxyfile', shell=True)
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = 'libicsneo'
|
||||
copyright = '2018-2024, Intrepid Control Systems, Inc.'
|
||||
author = 'Intrepid Control Systems, Inc.'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '@PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@ @BUILD_METADATA@'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This patterns also effect to html_static_path and html_extra_path
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
html_theme_options = {
|
||||
|
||||
}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# This is required for the alabaster theme
|
||||
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
|
||||
html_sidebars = {
|
||||
'**': [
|
||||
'relations.html', # needs 'show_related': True theme option to display
|
||||
'searchbox.html',
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'libicsneodoc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'libicsneo.tex', 'libicsneo Documentation',
|
||||
'Intrepid Control Systems, Inc.', 'manual'),
|
||||
]
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'libicsneo', 'libicsneo Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'libicsneo', 'libicsneo Documentation',
|
||||
author, 'libicsneo', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
********************
|
||||
**C API** (icsneoc)
|
||||
********************
|
||||
|
||||
.. Usage
|
||||
.. ======
|
||||
|
||||
.. Finding Devices
|
||||
.. ~~~~~~~~~~~~~~~~
|
||||
.. Finding a device is simple
|
||||
|
||||
.. Connecting to Devices
|
||||
.. ~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Reference
|
||||
==========
|
||||
|
||||
Typedefs
|
||||
~~~~~~~~~
|
||||
.. doxygentypedef:: devicehandle_t
|
||||
.. doxygentypedef:: neodevice_handle_t
|
||||
.. doxygentypedef:: devicetype_t
|
||||
|
||||
Structures
|
||||
~~~~~~~~~~~
|
||||
.. doxygenstruct:: neoversion_t
|
||||
:members:
|
||||
:undoc-members:
|
||||
|
||||
.. doxygenstruct:: neodevice_t
|
||||
:members:
|
||||
:undoc-members:
|
||||
|
||||
.. doxygenstruct:: neomessage_t
|
||||
:members:
|
||||
:undoc-members:
|
||||
|
||||
.. doxygenstruct:: neomessage_can_t
|
||||
:members:
|
||||
:undoc-members:
|
||||
|
||||
Functions
|
||||
~~~~~~~~~~
|
||||
.. doxygenfile:: icsneoc.h
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,14 @@
|
||||
=====
|
||||
C API
|
||||
=====
|
||||
|
||||
.. doxygenfile:: icsneoc.h
|
||||
:project: icsneoc
|
||||
.. doxygenfile:: device/neodevice.h
|
||||
:project: icsneoc
|
||||
.. doxygenfile:: communication/message/neomessage.h
|
||||
:project: icsneoc
|
||||
.. doxygenfile:: api/version.h
|
||||
:project: icsneoc
|
||||
.. doxygenfile:: api/event.h
|
||||
:project: icsneoc
|
||||
@@ -0,0 +1,43 @@
|
||||
==========
|
||||
C Examples
|
||||
==========
|
||||
|
||||
A variety of examples can be found within ``examples/c``, see below for an
|
||||
example that uses the polling API to receive CAN frames.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
size_t deviceCount = 10; // Pre-set to the size of your buffer before the icsneo_findAllDevices() call
|
||||
neodevice_t devices[10];
|
||||
icsneo_findAllDevices(devices, &deviceCount);
|
||||
printf("We found %ull devices\n", deviceCount);
|
||||
for(size_t i = 0; i < deviceCount; i++) {
|
||||
neodevice_t* myDevice = &devices[i];
|
||||
char desc[ICSNEO_DEVICETYPE_LONGEST_DESCRIPTION];
|
||||
size_t sz = ICSNEO_DEVICETYPE_LONGEST_DESCRIPTION;
|
||||
icsneo_describeDevice(myDevice, desc, &sz);
|
||||
printf("Found %s\n", desc); // "Found neoVI FIRE 2 CY2345"
|
||||
}
|
||||
neodevice_t* myDevice = &devices[0];
|
||||
if(!icsneo_openDevice(myDevice)) {
|
||||
neoevent_t error;
|
||||
if(icsneo_getLastError(&error))
|
||||
printf("Error! %s\n", error.description);
|
||||
}
|
||||
icsneo_goOnline(myDevice); // Start receiving messages
|
||||
icsneo_enableMessagePolling(myDevice); // Allow the use of icsneo_getMessages() later
|
||||
sleep(5);
|
||||
neomessage_t messages[50];
|
||||
size_t messageCount = 50;
|
||||
icsneo_getMessages(myDevice, messages, &messageCount, 0 /* non-blocking */);
|
||||
printf("We got %ull messages!\n", messageCount);
|
||||
for(size_t i = 0; i < messageCount; i++) {
|
||||
if(messages[i].type == ICSNEO_NETWORK_TYPE_CAN) {
|
||||
// A message of type CAN should be interperated a neomessage_can_t, so we can cast safely
|
||||
neomessage_can_t* canmsg = (neomessage_can_t*)&messages[i];
|
||||
// canmsg->arbid is valid here
|
||||
// canmsg->data is an uint8_t*, you can check canmsg->length for the length of the payload
|
||||
// canmsg->timestamp is the time recorded by the hardware in nanoseconds since (1/1/2007 12:00:00 GMT)
|
||||
}
|
||||
}
|
||||
icsneo_closeDevice(myDevice);
|
||||
@@ -0,0 +1,9 @@
|
||||
icsneoc
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
examples
|
||||
api
|
||||
@@ -0,0 +1,7 @@
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
The installation steps for the C API are the same as the C++ API as the C API is
|
||||
a wrapper for the C++ library. The ``LIBICSNEO_BUILD_ICSNEOC`` CMake option is
|
||||
default ``ON`` but note that the C API depends on this flag to build.
|
||||
@@ -1,31 +0,0 @@
|
||||
************************
|
||||
**C++ API** (icsneocpp)
|
||||
************************
|
||||
|
||||
.. Usage
|
||||
.. ======
|
||||
|
||||
.. Finding Devices
|
||||
.. ~~~~~~~~~~~~~~~~
|
||||
.. Finding a device is simple
|
||||
|
||||
.. Connecting to Devices
|
||||
.. ~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Reference
|
||||
==========
|
||||
|
||||
.. Classes
|
||||
.. ~~~~~~~~
|
||||
|
||||
.. Structures
|
||||
.. ~~~~~~~~~~~
|
||||
|
||||
.. Functions
|
||||
.. ~~~~~~~~~~
|
||||
|
||||
.. doxygennamespace:: icsneo
|
||||
|
||||
.. doxygenclass:: icsneo::Device
|
||||
:members:
|
||||
:undoc-members:
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,8 @@
|
||||
=======
|
||||
C++ API
|
||||
=======
|
||||
|
||||
.. doxygennamespace:: icsneo
|
||||
:members:
|
||||
:undoc-members:
|
||||
:content-only:
|
||||
@@ -0,0 +1,55 @@
|
||||
============
|
||||
API Concepts
|
||||
============
|
||||
|
||||
Overview
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Events convey information about the API's inner workings to the user. There are 3 severity levels: ``EventInfo``, ``EventWarning``, and ``Error``.
|
||||
**However, the API treats events of severities** ``EventInfo`` **and** ``EventWarning`` **differently than those of severity** ``Error`` **.**
|
||||
From here on out, when we (and the API functions) refer to "events", we refer exclusively to those of severities ``EventInfo`` and ``EventWarning``, which use the events_ system.
|
||||
Those of severity ``Error`` are referred to as "errors", which use a separate errors_ system.
|
||||
|
||||
Events should periodically be read out in order to avoid overflowing, and the last error should be read out immediately after an API function fails.
|
||||
|
||||
Additionally, `event callbacks`_ can be registered, which may remove the need to periodically read events in some cases.
|
||||
|
||||
.. _events:
|
||||
|
||||
Events
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The API stores events in a single buffer that can has a default size of 10,000 events.
|
||||
This limit includes 1 reserved slot at the end of the buffer for a potential Event of type ``TooManyEvents`` and severity ``EventWarning``, which is added when there are too many events for the buffer to hold.
|
||||
This could occur if the events aren't read out by the user often enough, or if the user sets the size of the buffer to a value smaller than the number of existing events.
|
||||
There will only ever be one of these ``TooManyEvents`` events, and it will always be located at the very end of the buffer if it exists.
|
||||
Because of this reserved slot, the buffer by default is able to hold 9,999 events. If capacity is exceeded, the oldest events in the buffer are automatically discarded until the buffer is exactly at capacity again.
|
||||
When events are read out by the user, they are removed from the buffer. If an event filter is used, only the filtered events will be removed from the buffer.
|
||||
|
||||
In a multithreaded environment, all threads will log their events to the same buffer. In this case, the order of events will largely be meaningless, although the behavior of ``TooManyEvents`` is still guaranteed to be as described above.
|
||||
|
||||
.. _event callbacks:
|
||||
|
||||
Event Callbacks
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Users may register event callbacks, which are automatically called whenever a matching event is logged.
|
||||
Message callbacks consist of a user-defined ``std::function< void( std::shared_ptr<APIEvent> ) >`` and optional EventFilter used for matching.
|
||||
If no EventFilter is provided, the default-constructed one will be used, which matches any event.
|
||||
Registering a callback returns an ``int`` representing the id of the callback, which should be stored by the user and later used to remove the callback when desired.
|
||||
Note that this functionality is only available in C and C++. C does not currently support filters.
|
||||
|
||||
Event callbacks are run after the event has been added to the buffer of events. The buffer of events may be safely modified within the callback, such as getting (flushing) the type and severity of the triggering event.
|
||||
Using event callbacks in this manner means that periodically reading events is unnecessary.
|
||||
|
||||
.. _errors:
|
||||
|
||||
Errors
|
||||
~~~~~~~~~
|
||||
|
||||
The error system is threadsafe and separate from the events_ system.
|
||||
Each thread keeps track of the last error logged on it, and getting the last error will return the last error from the calling thread, removing it in the process.
|
||||
Trying to get the last error when there is none will return an event of type ``NoErrorFound`` and severity ``EventInfo``.
|
||||
|
||||
The API also contains some threads for internal use which may potentially log errors of their own and are inaccessible to the user.
|
||||
These threads have been marked to downgrade any errors that occur on them to severity ``EventWarning`` and will log the corresponding event in the events_ system described above.
|
||||
@@ -1,64 +1,6 @@
|
||||
****************
|
||||
**API Usage**
|
||||
****************
|
||||
|
||||
API Concepts
|
||||
================
|
||||
|
||||
Overview
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Events convey information about the API's inner workings to the user. There are 3 severity levels: ``EventInfo``, ``EventWarning``, and ``Error``.
|
||||
**However, the API treats events of severities** ``EventInfo`` **and** ``EventWarning`` **differently than those of severity** ``Error`` **.**
|
||||
From here on out, when we (and the API functions) refer to "events", we refer exclusively to those of severities ``EventInfo`` and ``EventWarning``, which use the events_ system.
|
||||
Those of severity ``Error`` are referred to as "errors", which use a separate errors_ system.
|
||||
|
||||
Events should periodically be read out in order to avoid overflowing, and the last error should be read out immediately after an API function fails.
|
||||
|
||||
Additionally, `event callbacks`_ can be registered, which may remove the need to periodically read events in some cases.
|
||||
|
||||
.. _events:
|
||||
|
||||
Events
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The API stores events in a single buffer that can has a default size of 10,000 events.
|
||||
This limit includes 1 reserved slot at the end of the buffer for a potential Event of type ``TooManyEvents`` and severity ``EventWarning``, which is added when there are too many events for the buffer to hold.
|
||||
This could occur if the events aren't read out by the user often enough, or if the user sets the size of the buffer to a value smaller than the number of existing events.
|
||||
There will only ever be one of these ``TooManyEvents`` events, and it will always be located at the very end of the buffer if it exists.
|
||||
Because of this reserved slot, the buffer by default is able to hold 9,999 events. If capacity is exceeded, the oldest events in the buffer are automatically discarded until the buffer is exactly at capacity again.
|
||||
When events are read out by the user, they are removed from the buffer. If an event filter is used, only the filtered events will be removed from the buffer.
|
||||
|
||||
In a multithreaded environment, all threads will log their events to the same buffer. In this case, the order of events will largely be meaningless, although the behavior of ``TooManyEvents`` is still guaranteed to be as described above.
|
||||
|
||||
.. _event callbacks:
|
||||
|
||||
Event Callbacks
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Users may register event callbacks, which are automatically called whenever a matching event is logged.
|
||||
Message callbacks consist of a user-defined ``std::function< void( std::shared_ptr<APIEvent> ) >`` and optional EventFilter used for matching.
|
||||
If no EventFilter is provided, the default-constructed one will be used, which matches any event.
|
||||
Registering a callback returns an ``int`` representing the id of the callback, which should be stored by the user and later used to remove the callback when desired.
|
||||
Note that this functionality is only available in C and C++. C does not currently support filters.
|
||||
|
||||
Event callbacks are run after the event has been added to the buffer of events. The buffer of events may be safely modified within the callback, such as getting (flushing) the type and severity of the triggering event.
|
||||
Using event callbacks in this manner means that periodically reading events is unnecessary.
|
||||
|
||||
.. _errors:
|
||||
|
||||
Errors
|
||||
~~~~~~~~~
|
||||
|
||||
The error system is threadsafe and separate from the events_ system.
|
||||
Each thread keeps track of the last error logged on it, and getting the last error will return the last error from the calling thread, removing it in the process.
|
||||
Trying to get the last error when there is none will return an event of type ``NoErrorFound`` and severity ``EventInfo``.
|
||||
|
||||
The API also contains some threads for internal use which may potentially log errors of their own and are inaccessible to the user.
|
||||
These threads have been marked to downgrade any errors that occur on them to severity ``EventWarning`` and will log the corresponding event in the events_ system described above.
|
||||
|
||||
===============
|
||||
Device Concepts
|
||||
================
|
||||
===============
|
||||
|
||||
Open/Close Status
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -0,0 +1,52 @@
|
||||
============
|
||||
C++ Examples
|
||||
============
|
||||
|
||||
A variety of examples can be found within ``examples/cpp``, see below for an
|
||||
example that uses the polling API to receive CAN frames.
|
||||
|
||||
The C++ API is designed to be modern and easy to use. All library functions and
|
||||
classes are in the namespace ``icsneo``. Most applications will start by calling
|
||||
``icsneo::FindAllDevices()``. This will return an ``std::vector`` of
|
||||
``std::shared_ptr<icsneo::Device>`` objects. You will want to keep a copy of the
|
||||
``shared_ptr`` to any devices you want to use, as allowing it to go out of scope
|
||||
will automatically close the device and free all memory associated with it.
|
||||
|
||||
Any time you get bus traffic from the API, you will receive it as an
|
||||
``std::shared_ptr<icsneo::Message>``. The message will be valid as long as the
|
||||
``shared_ptr`` stays in scope. Checking the type of the message allows you to
|
||||
cast it accordingly and access extra data for certain protocols. For instance,
|
||||
casting an ``icsneo::Message`` to an ``icsneo::CANMessage`` allows you to access
|
||||
the arbitration ID.
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
std::vector<std::shared_ptr<icsneo::Device>> devices = icsneo::FindAllDevices();
|
||||
std::cout << devices.size() << " found!" << std::endl;
|
||||
for(auto& device : devices)
|
||||
std::cout << "Found " << device->describe() << std::endl; // "Found neoVI FIRE 2 CY2345"
|
||||
std::shared_ptr<icsneo::Device> myDevice = devices[0];
|
||||
if(!myDevice->open()) // Device tried and failed to open, print the last error
|
||||
std::cout << icsneo::GetLastError() << std::endl;
|
||||
myDevice->goOnline(); // Start receiving messages
|
||||
myDevice->enableMessagePolling(); // Allow the use of myDevice->getMessages() later
|
||||
// Alternatively, assign a callback for new messages
|
||||
std::this_thread::wait_for(std::chrono::seconds(5));
|
||||
std::vector<std::shared_ptr<icsneo::Message>> messages = myDevice->getMessages();
|
||||
std::cout << "We got " << messages.size() << " messages!" << std::endl;
|
||||
for(auto& msg : messages) {
|
||||
switch(msg->network.getType()) {
|
||||
case icsneo::Network::Type::CAN:
|
||||
case icsneo::Network::Type::SWCAN:
|
||||
case icsneo::Network::Type::LSFTCAN: {
|
||||
// A message of type CAN is guaranteed to be a CANMessage, so we can static cast safely
|
||||
auto canmsg = std::static_pointer_cast<icsneo::CANMessage>(msg);
|
||||
// canmsg->arbid is valid here
|
||||
// canmsg->data is an std::vector<uint8_t>, you can check .size() for the DLC of the message
|
||||
// canmsg->timestamp is the time recorded by the hardware in nanoseconds since (1/1/2007 12:00:00 GMT)
|
||||
}
|
||||
default:
|
||||
// Handle others
|
||||
}
|
||||
}
|
||||
myDevice->close();
|
||||
@@ -0,0 +1,11 @@
|
||||
icsneocpp
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
deviceconcepts
|
||||
apiconcepts
|
||||
examples
|
||||
api
|
||||
@@ -0,0 +1,39 @@
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
The minimum requirements to build libicsneo are:
|
||||
- CMake version 3.12 or newer
|
||||
- A C++17 compiler
|
||||
- libusb and libpcap on Linux and macOS
|
||||
|
||||
|
||||
Building library & examples
|
||||
===========================
|
||||
|
||||
For a list of available configuration options, see the ``option()`` entries in
|
||||
``CMakeLists.txt``.
|
||||
|
||||
To build libicsneo with default options:
|
||||
#. ``cmake -B build``
|
||||
#. ``cmake --build build``
|
||||
|
||||
Adding to existing projects
|
||||
===========================
|
||||
|
||||
libicsneo supports being added as a sub-projects with CMake's
|
||||
``add_subdirectory()``.
|
||||
|
||||
#. Clone libicsneo into the desired location within the project
|
||||
#. Add ``add_subdirectory(path/to/libicsneo)`` to ``CMakeLists.txt``
|
||||
#. Link the project to libicsneo with ``target_link_libraries(app icsneocpp)``
|
||||
|
||||
Linux udev Rules
|
||||
================
|
||||
|
||||
Linux users may want to install the included udev rules to run libicsneo based
|
||||
applications without root, this can be done with:
|
||||
``cp 99-intrepidcs.rules /etc/udev/rules.d/``
|
||||
@@ -0,0 +1,9 @@
|
||||
==========
|
||||
Python API
|
||||
==========
|
||||
|
||||
.. automodule:: icsneopy
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
:special-members: __init__
|
||||
@@ -0,0 +1,52 @@
|
||||
===============
|
||||
Python Examples
|
||||
===============
|
||||
|
||||
Transmit CAN frames on HSCAN
|
||||
============================
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import icsneopy
|
||||
|
||||
devices: list[icsneopy.Device] = icsneopy.find_all_devices()
|
||||
|
||||
# grab the first/only device found
|
||||
device: icsneopy.Device = devices[0]
|
||||
|
||||
message = icsneopy.CANMessage()
|
||||
message.network = icsneopy.Network(icsneopy.Network.NetID.HSCAN)
|
||||
message.arbid = 0x56
|
||||
message.data = (0x11, 0x22, 0x33)
|
||||
|
||||
device.open()
|
||||
|
||||
device.go_online()
|
||||
|
||||
device.transmit(message)
|
||||
|
||||
Receive CAN frames on HSCAN
|
||||
===========================
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import icsneopy
|
||||
import time
|
||||
|
||||
devices: list[icsneopy.Device] = icsneopy.find_all_devices()
|
||||
|
||||
# grab the first/only device found
|
||||
device: icsneopy.Device = devices[0]
|
||||
|
||||
def on_message(message: icsneopy.CANMessage):
|
||||
print(message.arbid, message.data)
|
||||
message_filter = icsneopy.MessageFilter(icsneopy.Network.NetID.HSCAN)
|
||||
callback = icsneopy.MessageCallback(on_message, message_filter)
|
||||
|
||||
device.add_message_callback(callback)
|
||||
|
||||
device.open()
|
||||
device.go_online()
|
||||
|
||||
# rx for 10s
|
||||
time.sleep(10)
|
||||
@@ -0,0 +1,9 @@
|
||||
========
|
||||
icsneopy
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
examples
|
||||
api
|
||||
+7
-7
@@ -1,10 +1,10 @@
|
||||
Welcome to libicsneo's documentation!
|
||||
=======================================
|
||||
libicsneo
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:caption: Documentation
|
||||
:maxdepth: 1
|
||||
:caption: API Documentation
|
||||
|
||||
Usage
|
||||
icsneocpp
|
||||
icsneoc
|
||||
icsneocpp/index
|
||||
icsneopy/index
|
||||
icsneoc/index
|
||||
|
||||
@@ -1 +1,4 @@
|
||||
breathe==4.12.0
|
||||
sphinx
|
||||
icsneopy
|
||||
breathe
|
||||
sphinx_rtd_theme
|
||||
|
||||
Reference in New Issue
Block a user