Merge pull request #16 from uv-software/development

Release candidate 5 for version 0.3

Deployment.md

@@ -1,6 +1,6 @@
 ### CAN API V3 Wrapper Library for Kvaser CAN Interfaces (Windows®)
 
-_Copyright © 2017-2023 Uwe Vogt, UV Software, Berlin ([email protected])_
+_Copyright © 2017-2024 Uwe Vogt, UV Software, Berlin ([email protected])_
 _All rights reserved._
 
 # Deployment
@@ -26,11 +26,12 @@ _All rights reserved._
   - `Update CAN API V3 testing sources to rev. `_nnn_ \
     `- `_list of major changes (optional)_
 4. Check and update the version and date information in the following files:
+  - `$(PROJROOT)\Sources\Version.h`
   - `$(PROJROOT)\Sources\KvaserCAN.h`
   - `$(PROJROOT)\Sources\KvaserCAN.cpp`
-  - `$(PROJROOT)\Sources\Wrapper\can_api.cpp`
-  - `$(PROJROOT)\Libraries\CANAPI\Resource.rc`
-  - `$(PROJROOT)\Libraries\KvaserCAN\Resource.rc`
+  - `$(PROJROOT)\Sources\Wrapper\can_api.c`
+  - `$(PROJROOT)\Libraries\CANAPI\uvcankvl.rc`
+  - `$(PROJROOT)\Libraries\PeakCAN\KvaserCAN.rc`
   - `$(PROJROOT)\Utilities\can_moni\Driver.h`
   - `$(PROJROOT)\Utilities\can_test\Driver.h`
 
@@ -71,34 +72,35 @@ _All rights reserved._
 3. Run the batch files in the project root directory:
   - `C:\Users\haumea>cd C:\Projects\CAN\Drivers\KvaserCAN`
   - `C:\Projects\CAN\Drivers\KvaserCAN>x86_build.bat`
-  - `C:\Projects\CAN\Drivers\KvaserCAN>x64_build.bat`
   - `C:\Projects\CAN\Drivers\KvaserCAN>x86_install.bat`
+  - `C:\Projects\CAN\Drivers\KvaserCAN>x64_build.bat`
   - `C:\Projects\CAN\Drivers\KvaserCAN>x64_install.bat`
 4. Build the CAN API V3 GoogleTest program:
   - `C:\Users\haumea>cd C:\Projects\CAN\Drivers\KvaserCAN\Tests`
+  - `C:\Projects\CAN\Drivers\KvaserCAN\Tests>x86_build.bat`
   - `C:\Projects\CAN\Drivers\KvaserCAN\Tests>x64_build.bat`
 5. Run the CAN API V3 GoogleTest program with two Kvaser CAN devices in CAN 2.0 mode:
-  - `C:\Projects\CAN\Drivers\KvaserCAN\Tests>x64\Debug\kvl_testing --can_dut1="Kvaser CAN Channel 0" --can_dut2="Kvaser CAN Channel 1" --gtest_output=xml:TestReport_KvaserCAN.xml --run_all=YES --smoketest_frames=100000` [...]
+  - `C:\Projects\CAN\Drivers\KvaserCAN\Tests>Debug\kvl_testing --can_dut1="Kvaser CAN Channel 0" --can_dut2="Kvaser CAN Channel 1" --gtest_output=xml:TestReport_KvaserCAN.xml --run_all=YES --smoketest_frames=100000` [...]
   - _If there is any error then **stop** here or create an issue for each error in the repo._
   - Copy the test report into the binary's directory `$(PROJROOT)\Binaries`.
-6. Run the CAN API V3 GoogleTest programwith two Kvaser CAN devices in CAN FD mode:
+6. Run the CAN API V3 GoogleTest program with two Kvaser CAN devices in CAN FD mode:
   - `C:\Projects\CAN\Drivers\KvaserCAN\Tests>x64\Debug\kvl_testing --can_dut1="Kvaser CAN Channel 1" --can_dut2="Kvaser CAN Channel 2" --can_bitrate=DEFAULT --can_mode=CANFD+BRS  --gtest_output=xml:TestReport_KvaserCAN_FD.xml --run_all=YES --smoketest_frames=100000` [...]
   - _If there is any error then **stop** here or create an issue for each error in the repo._
   - Copy the test report into the binary's directory `$(PROJROOT)\Binaries`.
 7. Pack the artifacts into a .zip-archive, e.g. `artifacts.zip`:
   - `$(PROJROOT)\Binaries\*.*`
   - `$(PROJROOT)\Includes\*.*`
   - `$(PROJROOT)\README.md`
-  - `$(PROJROOT)\LICENSE`
+  - `$(PROJROOT)\LICENSE.*`
 8. Double check and update the [`README.md`](https://github.com/uv-software/KvaserCAN-Wrapper/blob/main/README.md) on GitHub (or insert just a blank).
 
 ### Procedure
 
 1. Click on `Draft a new release` in the [GitHub](https://github.com/uv-software/KvaserCAN-Wrapper) repo.
 2. Fill out all required fields:
-  - Tag version: e.g `v0.2.5` (cf. semantic versioning)
+  - Tag version: e.g `v0.3` (cf. semantic versioning)
   - Target: `main` (default branch)
-  - Release title: e.g. `Release of November 5, 2023`
+  - Release title: e.g. `Release of January 19, 2038`
   - Change-log: list all major changes, e.g. from commit comments
   - Assets: drag and drop the artifacts archive (see above)
 3. Click on `Publish release`.

Examples/Python/CANAPI.py

@@ -52,9 +52,9 @@
     Interface API for various CAN interfaces from different
     vendors running under multiple operating systems.
 
-    $Author: haumea $
+    $Author: quaoar $
 
-    $Rev: 1258 $
+    $Rev: 1278 $
 """
 from ctypes import *
 import platform
@@ -69,7 +69,7 @@
 
 # CAN API V3 - Python Wrapper
 #
-CAN_API_V3_PYTHON = {'major': 0, 'minor': 2, 'patch': 0}
+CAN_API_V3_PYTHON = {'major': 0, 'minor': 3, 'patch': 1}
 
 # CAN Identifier Ranges
 #
@@ -122,6 +122,13 @@
     (49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64): c_uint8(0xF)
 }
 
+# CAN Acceptance Filter: (code ^ id) & mask == 0
+#
+CANACC_CODE_11BIT = 0x000  # mask for 11-bit acceptance code
+CANACC_MASK_11BIT = 0x000  # mask for 11-bit acceptance mask
+CANACC_CODE_29BIT = 0x00000000  # mask for 29-bit acceptance code
+CANACC_MASK_29BIT = 0x00000000  # mask for 29-bit acceptance mask
+
 # CAN 2.0 Predefined Bit-rates (as index acc. CiA)
 #
 CANBTR_INDEX_1M = c_int32(0)     # bit-rate: 1000 kbit/s
@@ -638,6 +645,133 @@ def bitrate(self):
             print('+++ exception: {}'.format(e))
             raise
 
+    def filter11bit(self, code, mask):
+        """
+          sets a 11-bit filter for the CAN controller.
+
+          :param code: 11-bit code for the filter (or None)
+          :param mask: 11-bit mask for the filter (or None)
+          :return: result, code, mask
+            result: 0 if successful, or a negative value on error
+            code: 11-bit code for the filter
+            mask: 11-bit mask for the filter
+        """
+        try:
+            # set the 11-bit filter (if code or mask are not None)
+            if code is not None or mask is not None:
+                __filter = c_uint64(0)
+                if code is not None:
+                    __filter.value = code << 32
+                if mask is not None:
+                    __filter.value |= mask & 0xFFFFFFFF
+                result = self.__m_library.can_property(self.__m_handle, 42, byref(__filter), 8)
+                if result < 0:
+                    return int(result), None, None
+            # get the 11-bit filter
+            __value = c_uint64(0)
+            result = self.__m_library.can_property(self.__m_handle, 40, byref(__value), 8)
+            if result < 0:
+                return int(result), None, None
+            return int(result), int(__filter.value >> 32), int(__filter.value & 0xFFFFFFFF)
+        except Exception as e:
+            print('+++ exception: {}'.format(e))
+            raise
+
+    def filter29bit(self, code, mask):
+        """
+          sets a 29-bit filter for the CAN controller.
+
+          :param code: 29-bit code for the filter (or None)
+          :param mask: 29-bit mask for the filter (or None)
+          :return: result, code, mask
+            result: 0 if successful, or a negative value on error
+            code: 29-bit code for the filter
+            mask: 29-bit mask for the filter
+        """
+        try:
+            # set the 29-bit filter (if code or mask are not None)
+            if code is not None or mask is not None:
+                __filter = c_uint64(0)
+                if code is not None:
+                    __filter.value = code << 32
+                if mask is not None:
+                    __filter.value |= mask & 0xFFFFFFFF
+                result = self.__m_library.can_property(self.__m_handle, 43, byref(__filter), 8)
+                if result < 0:
+                    return int(result), None, None
+            # get the 29-bit filter
+            __value = c_uint64(0)
+            result = self.__m_library.can_property(self.__m_handle, 41, byref(__value), 8)
+            if result < 0:
+                return int(result), None, None
+            return int(result), int(__filter.value >> 32), int(__filter.value & 0xFFFFFFFF)
+        except Exception as e:
+            print('+++ exception: {}'.format(e))
+            raise
+
+    def hardware(self):
+        """
+          retrieves the hardware version of the CAN controller
+          board as a zero-terminated string.
+
+          note: API function 'can_hardware' is marked as deprecated.
+
+          :return: version
+            version: version information as string
+        """
+        try:
+            self.__m_library.can_hardware.restype = c_char_p
+            version_c = self.__m_library.can_hardware(self.__m_handle)
+            if version_c is not None:
+                return version_c.decode('utf-8')
+            else:
+                raise Exception('+++ error: can_hardware returned None')
+        except Exception as e:
+            print('+++ exception: {}'.format(e))
+            raise
+
+    def firmware(self):
+        """
+          retrieves the firmware version of the CAN controller
+          board as a zero-terminated string.
+
+          note: API function 'can_firmware' is marked as deprecated.
+
+          :return: version
+            version: version information as string
+        """
+        try:
+            self.__m_library.can_firmware.restype = c_char_p
+            version_c = self.__m_library.can_firmware(self.__m_handle)
+            if version_c is not None:
+                return version_c.decode('utf-8')
+            else:
+                raise Exception('+++ error: can_firmware returned None')
+        except Exception as e:
+            print('+++ exception: {}'.format(e))
+            raise
+
+    def software(self):
+        """
+          retrieves version information of the CAN API V3 DLL
+          as a zero-terminated string.
+
+          note: API function 'can_version' is marked as deprecated.
+
+          :return: version
+            version: version information as string
+        """
+        try:
+            self.__m_library.can_version.restype = c_char_p
+            version_c = self.__m_library.can_version()
+            if version_c is not None:
+                return version_c.decode('utf-8')
+            else:
+                raise Exception('+++ error: can_version returned None')
+        except Exception as e:
+            print('+++ exception: {}'.format(e))
+            raise
+
     @staticmethod
     def version():
         """
@@ -704,6 +838,7 @@ def len2dlc(length):
     print(CANAPI.version())
     print('>>> can = CANAPI(' + lib + ')')
     can = CANAPI(lib)
+    print(can.software())
 
     # initialize the CAN interface
     print('>>> can.init({}, 0x{:02X})'.format(chn, opMode.byte))
@@ -716,6 +851,20 @@ def len2dlc(length):
     else:
         print('>>> can.status() >>> 0x{:02X}'.format(status.byte))
 
+    # set acceptance filter
+    code = CANACC_CODE_11BIT
+    mask = CANACC_MASK_11BIT
+    print('>>> can.filter11bit(0x{:03X}, 0x{:03X})'.format(code, mask))
+    res, code, mask = can.filter11bit(code=code, mask=mask)
+    if res < CANERR_NOERROR:
+        print('+++ error: can.filter11bit returned {}'.format(res))
+    code = CANACC_CODE_29BIT
+    mask = CANACC_MASK_29BIT
+    print('>>> can.filter29bit(0x{:08X}, 0x{:08X})'.format(code, mask))
+    res, code, mask = can.filter29bit(code=code, mask=mask)
+    if res < CANERR_NOERROR:
+        print('+++ error: can.filter29bit returned {}'.format(res))
+
     # start the CAN controller
     if bitRate.index > 0:   # FIXME: Expected type 'int', got 'c_int32[int]' instead
         print('>>> can.start([{},[{},{},{},{},{}],[{},{},{},{},])'.format(bitRate.btr.frequency,
@@ -754,6 +903,10 @@ def len2dlc(length):
     else:
         print('>>> can.status() >>> 0x{:02X}'.format(status.byte))
 
+    # print some version information
+    print('>>> can.hardware() >>> ' + can.hardware())
+    print('>>> can.firmware() >>> ' + can.firmware())
+
     # shutdown the CAN interface
     print('>>> can.exit()')
     res = can.exit()
@@ -763,5 +916,5 @@ def len2dlc(length):
     # have a great time
     print('Bye, bye!')
 
-# * $Id: CANAPI.py 1258 2024-03-19 21:35:15Z haumea $ *** (c) UV Software, Berlin ***
+# * $Id: CANAPI.py 1278 2024-04-23 08:34:36Z quaoar $ *** (c) UV Software, Berlin ***
 #

Examples/Python/can_recv.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 from CANAPI import *
+import platform
 import argparse
 import signal
 import sys
@@ -9,10 +10,10 @@
 #
 def sigterm(signo, frame):
     print()
-#    print('>>> can.kill()')
-#    result = can.kill()
-#    if result < 0:
-#        print('+++ error: can.kill returned {}'.format(result))
+    print('>>> can.kill()')
+    result = can.kill()
+    if result < 0:
+        print('+++ error: can.kill returned {}'.format(result))
     print('>>> can.exit()')
     result = can.exit()
     if result < 0:
@@ -55,6 +56,7 @@ def sigterm(signo, frame):
 print(CANAPI.version())
 print('>>> can = CANAPI(' + lib + ')')
 can = CANAPI(lib)
+print(can.software())
 
 # initialize the CAN interface
 print('>>> can.init({}, 0x{:02X})'.format(chn, opMode.byte))
@@ -67,6 +69,20 @@ def sigterm(signo, frame):
 else:
     print('>>> can.status() >>> 0x{:02X}'.format(status.byte))
 
+# set acceptance filter
+code = CANACC_CODE_11BIT
+mask = CANACC_MASK_11BIT
+print('>>> can.filter11bit(0x{:03X}, 0x{:03X})'.format(code, mask))
+res, code, mask = can.filter11bit(code=code, mask=mask)
+if res < CANERR_NOERROR:
+    print('+++ error: can.filter11bit returned {}'.format(res))
+code = CANACC_CODE_29BIT
+mask = CANACC_MASK_29BIT
+print('>>> can.filter29bit(0x{:08X}, 0x{:08X})'.format(code, mask))
+res, code, mask = can.filter29bit(code=code, mask=mask)
+if res < CANERR_NOERROR:
+    print('+++ error: can.filter29bit returned {}'.format(res))
+
 # start the CAN controller
 if int(bitRate.index) > 0:   # FIXME: Expected type 'int', got 'c_int32[int]' instead
     print('>>> can.start([{},[{},{},{},{},{}],[{},{},{},{},])'.format(bitRate.btr.frequency,
@@ -147,6 +163,10 @@ def sigterm(signo, frame):
 else:
     print('>>> can.status() >>> 0x{:02X}'.format(status.byte))
 
+# print some version information
+print('>>> can.hardware() >>> ' + can.hardware())
+print('>>> can.firmware() >>> ' + can.firmware())
+
 # shutdown the CAN interface
 print('>>> can.exit()')
 res = can.exit()

Examples/Python/can_send.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 from CANAPI import *
+import platform
 import argparse
 import signal
 import sys
@@ -10,10 +11,10 @@
 #
 def sigterm(signo, frame):
     print()
-#    print('>>> can.kill()')
-#    result = can.kill()
-#    if result < 0:
-#        print('+++ error: can.kill returned {}'.format(result))
+    print('>>> can.kill()')
+    result = can.kill()
+    if result < 0:
+        print('+++ error: can.kill returned {}'.format(result))
     print('>>> can.exit()')
     result = can.exit()
     if result < 0:
@@ -68,6 +69,7 @@ def sigterm(signo, frame):
 print(CANAPI.version())
 print('>>> can = CANAPI(' + lib + ')')
 can = CANAPI(lib)
+print(can.software())
 
 # initialize the CAN interface
 print('>>> can.init({}, 0x{:02X})'.format(chn, opMode.byte))
@@ -137,6 +139,10 @@ def sigterm(signo, frame):
 else:
     print('>>> can.status() >>> 0x{:02X}'.format(status.byte))
 
+# print some version information
+print('>>> can.hardware() >>> ' + can.hardware())
+print('>>> can.firmware() >>> ' + can.firmware())
+
 # shutdown the CAN interface
 print('>>> can.exit()')
 res = can.exit()

README.md

@@ -159,9 +159,9 @@ A generic documentation of the CAN API V3 application programming interface can
 
 ### Dual-License
 
-This work is dual-licensed under the terms of the BSD 2-Clause "Simplified" License
+Except where otherwise noted, this work is dual-licensed under the terms of the BSD 2-Clause "Simplified" License
 and under the terms of the GNU General Public License v3.0 (or any later version).
-You can choose between one of them if you use this work in whole or in part.
+You can choose between one of them if you use these portions of this work in whole or in part.
 
 `SPDX-License-Identifier: BSD-2-Clause OR GPL-3.0-or-later`