Skip to content

Commit 1189f34

Browse files
uv-softwareuv-software
committed
Initial commit
0 parents  commit 1189f34

26 files changed

Lines changed: 2274 additions & 0 deletions

‎docs/.nojekyll‎

Whitespace-only changes.

‎docs/README.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
## CAN Interface API by UV Software
2+
3+
### Abstract
4+
5+
> **CAN API V3** is a wrapper specification by UV Software to have a uniform CAN Interface API for various CAN interfaces from different vendors running under multiple operating systems.
6+
7+
### Scope
8+
9+
The goal of the CAN API V3 project is to have a multi-vendor, cross-platform CAN Interface API (Application Programming Interface). Each CAN adapter manufacturer provides its own CAN software SDK (Software Development Kit) for the development of CAN applications based on the provided SDK. Unfortunately, the APIs of the different manufacturers are not compatible with each other. The CAN Interface API by UV Software (CAN API V3) solves the problems arising from this incompatibility.
10+
11+
This documentation is a generic description of the CAN API V3 Software Development Kit. It describes all functions, methods, attributes, properties, and data types of the CAN API V3 Application Programming Interface without referencing the specifics of the individual CAN API V3 implementations.
12+
13+
On the other hand, this documentation serves as a requirements specification for the implementation of a CAN API V3 wrapper library based upon a vendor-specific SDK or based upon an own CAN driver implementation. You just need to add the word “shall” to each sentence in your mind.
14+
15+
### API
16+
17+
The CAN API V3 application programming interface is defined for the **C** programming language.
18+
The wrapper implementations also provide application programming interfaces for **C++** and **Swift** (macOS® only).
19+
20+
CAN API V3 provides the following main functions respectively methods:
21+
22+
[can_test()](/reference/can_test#can_test) respectively [ProbeChannel()](/reference/can_test#probechannel) - probe if a CAN channel is available
23+
24+
[can_init()](/reference/can_init#can_init) respectively [InitializeChannel()](/reference/can_init#initializechannel) - initialize a CAN channel
25+
26+
[can_exit()](/reference/can_exit#can_exit) respectively [TeardownChannel()](/reference/can_exit#teardownchannel) - teardown a CAN channel
27+
28+
[can_kill()](/reference/can_kill#can_kill) respectively [SignalChannel()](/reference/can_kill#signalchannel) - signal waiting event objects of a CAN channel
29+
30+
[can_start()](/reference/can_start#can_start) respectively [StartController()](/reference/can_start#startcontroller) - start the CAN controller of a CAN channel
31+
32+
[can_reset()](/reference/can_reset#can_reset) respectively [ResetController()](/reference/can_reset#resetcontroller) - stop the CAN controller of a CAN channel
33+
34+
[can_write()](/reference/can_write#can_write) respectively [WriteMessage()](/reference/can_write#writemessage) - send a CAN message on a CAN channel
35+
36+
[can_read()](/reference/can_read#can_read) respectively [ReadMessage()](/reference/can_read#readmessage) - read one CAN message from the receive queue of a CAN channel
37+
38+
[can_status()](/reference/can_status#can_status) respectively [GetStatus()](/reference/can_status#getstatus) - get the [status register](/reference/status_register#name) from the CAN controller of a CAN channel
39+
40+
[can_bitrate()](/reference/can_bitrate#can_bitrate) respectively [GetBitrate()](/reference/can_bitrate#getbitrate) and [GetBusSpeed()](/reference/can_bitrate#getbusspeed) - get the CAN bit-rate settings from the CAN controller of a CAN channel
41+
42+
[can_property()](/reference/can_property#can_property) respectively [GetProperty()](/reference/can_property#getproperty) and [SetProperty()](/reference/can_property#setproperty) - get or modify a property value of a CAN channel or of the CAN API library
43+
44+
### Wrapper
45+
46+
Several CAN API V3 wrapper implementations exist for Windows®, macOS® and Linux®. They can be downloaded from / cloned at my GitHub repositories.
47+
48+
Please note the copyright and license agreements in the appropriated repository.
49+
50+
#### Windows®
51+
52+
[CAN API V3 Wrapper Library for Peak-System PCAN® Interfaces](https://github.com/uv-software/PCANBasic-Wrapper)
53+
54+
[CAN API V3 Wrapper Library for Kvaser CAN Interfaces](https://github.com/uv-software/KvaserCAN-Wrapper)
55+
56+
[Library for CAN-over-Serial-Line Interfaces (SLCAN Protocol)](https://github.com/uv-software/SerialCAN)
57+
58+
#### macOS®
59+
60+
[CAN API V3 Wrapper Library for PCAN-USB Interfaces from PEAK-System](https://github.com/mac-can/PCBUSB-Wrapper)
61+
62+
[macOS® Driver and SDK for USB CAN Interfaces from Kvaser](https://github.com/mac-can/KvaserCAN-Library)
63+
64+
[macOS® Driver and SDK for TouCAN USB Interfaces from Rusoku](https://github.com/mac-can/RusokuCAN.dylib)
65+
66+
[Library for CAN-over-Serial-Line Interfaces (SLCAN Protocol)](https://github.com/mac-can/SerialCAN)
67+
68+
#### Linux®
69+
70+
[Library for CAN-over-Serial-Line Interfaces (SLCAN Protocol)](https://github.com/mac-can/SerialCAN)
71+
72+
### Donate
73+
74+
These projects are developed and maintained in my spare time.
75+
If you like them (all of them, or just one) I would be very happy if you donate to my work.
76+
77+
78+
[copyright](/copyright.md ':include')

‎docs/_sidebar.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- docs/_sidebar.md -->
2+
3+
* [CAN API V3](/)
4+
* **Reference**
5+
* [Probe a CAN Channel](/reference/can_test)
6+
* [Initialize a CAN Channel](/reference/can_init)
7+
* [Teardown a CAN Channel](/reference/can_exit)
8+
* [Signal a CAN Channel](/reference/can_kill)
9+
* [Start the CAN Controller](/reference/can_start)
10+
* [Stop the CAN Controller](/reference/can_reset)
11+
* [Send a CAN Message](/reference/can_write)
12+
* [Read a CAN Message](/reference/can_read)
13+
* [Get Status Register](/reference/can_status)
14+
* [Get CAN Bit-rate Settings](/reference/can_bitrate)
15+
* [Get or Modify a Property Value](/reference/can_property)
16+
* [Message Format](/reference/message_format)
17+
* [Status Register](/reference/status_register)
18+
* [Bit-rate Settings](/reference/bitrate_settings)
19+
* [Operation Modes](/reference/operation_modes)
20+
* [Channel States](/reference/channel_states)
21+
* [Property IDs](/reference/property_ids)
22+
* [Error Codes](/reference/error_codes)
23+
* [History](/history)
24+
* [Changes](/changes)

‎docs/changes.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
| Rev. | Date | Author | Changes |
2+
| :--- | :------: | :------ | :--------------- |
3+
| 1.0 | 09/09/23 | U. Vogt | Initial revision |

‎docs/copyright.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
2+
---
3+
4+
All company, product and service names mentioned in this documentation may be trademarks, registered trademarks, or service marks of their respective owners.
5+
6+
Except where otherwise noted, this documentation is licensed under term of the [CC Attribution-Share Alike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/deed.en) license.
7+
8+
Copyright &copy; 2002-2023 by Uwe Vogt, UV Software, Berlin.
9+
10+
Happy CANgineering [:heart:](https://github.com/sponsors/mac-can)

‎docs/history.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
## CAN Interface API by UV Software
2+
3+
Originally, the CAN Interface API was based on a CAN interface definition as part of a microcontroller hardware abstraction layer for an 82527-compatible on-chip CAN controller. It was developed for use by (simple hand-coded) CANopen applications and migrated to different microcontroller types (even if the CAN peripherals on that micro had a different design).
4+
5+
### CAN API V1
6+
7+
What works on microcontrollers should also work on PC. I started to use this interface definition as a wrapper specification for different CAN devices from various vendors: e.g. for IXXAT, PEAK, Vector, Kvaser, and also for Linux-CAN (aka SocketCAN).
8+
9+
### CAN API V2
10+
11+
Dealing around with 14 virtual Basic-CAN messages boxes and a FIFO upon a virtual Full-CAN message box was a little bit over-engineered and error-prone. I optimized the interface definition to have an easy to use API following an *init-start-read-write-stop-exit* pattern.
12+
13+
### CAN API V3
14+
15+
Version 3 is the latest adaption of the CAN API wrapper specification. As new features it supports CAN FD long frames and fast frames, selectable operation modes, blocking read, and is multi-channel capable. Additionally it provides companion modules for bit-rate conversion and message formatting.
16+
17+
18+
[copyright](/copyright.md ':include')

‎docs/images/logo.png‎

2.33 KB
Loading

‎docs/index.html‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<title>Document</title>
6+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
7+
<meta name="description" content="Description">
8+
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
9+
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
10+
</head>
11+
<body>
12+
<div id="app"></div>
13+
<script>
14+
window.$docsify = {
15+
name: '',
16+
repo: '',
17+
loadSidebar: true,
18+
autoHeader: true,
19+
logo: '/images/logo.png',
20+
alias: {
21+
'/.*/_sidebar.md': '/_sidebar.md',
22+
},
23+
subMaxLevel: 3
24+
}
25+
</script>
26+
<!-- Docsify v4 -->
27+
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
28+
</body>
29+
</html>

‎docs/reference/bitrate_settings.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
### NAME
2+
3+
> *can_bitrate_t* - CAN bit-rate settings for arbitration phase and data phase
4+
5+
### SYNOPSIS
6+
7+
**C/C++ Defines**
8+
```C++
9+
#define CANBTR_INDEX_1M (0)
10+
#define CANBTR_INDEX_800K (-1)
11+
#define CANBTR_INDEX_500K (-2)
12+
#define CANBTR_INDEX_250K (-3)
13+
#define CANBTR_INDEX_125K (-4)
14+
#define CANBTR_INDEX_100K (-5)
15+
#define CANBTR_INDEX_50K (-6)
16+
#define CANBTR_INDEX_20K (-7)
17+
#define CANBTR_INDEX_10K (-8)
18+
```
19+
<a id="can_bitrate_t"></a>
20+
<a id="can_speed_t"></a>
21+
**C/C++ Typedef**
22+
```C++
23+
typedef union can_bitrate_t_ {
24+
int32_t index;
25+
struct {
26+
int32_t frequency;
27+
struct {
28+
uint16_t brp;
29+
uint16_t tseg1;
30+
uint16_t tseg2;
31+
uint16_t sjw;
32+
uint8_t sam;
33+
} nominal;
34+
struct {
35+
uint16_t brp;
36+
uint16_t tseg1;
37+
uint16_t tseg2;
38+
uint16_t sjw;
39+
} data;
40+
} btr;
41+
} can_bitrate_t;
42+
43+
typedef struct can_speed_t_ {
44+
struct {
45+
bool _reserved;
46+
float speed;
47+
float samplepoint;
48+
} nominal;
49+
struct {
50+
bool _reserved;
51+
float speed;
52+
float samplepoint;
53+
} data;
54+
} can_speed_t;
55+
```
56+
**C/C++ Alias**
57+
```C++
58+
typedef can_bitrate_t CANAPI_Bitrate_t;
59+
60+
typedef can_speed_t CANAPI_BusSpeed_t;
61+
```
62+
<a id="struct_bitrate"></a>
63+
<a id="struct_speed"></a>
64+
**Swift Type**
65+
```Swift
66+
public enum CiaIndex: Int {
67+
case Index1000kbps = 0
68+
case Index800kbps = 1
69+
case Index500kbps = 2
70+
case Index250kbps = 3
71+
case Index125kbps = 4
72+
case Index100kbps = 5
73+
case Index50kbps = 6
74+
case Index20kbps = 7
75+
case Index10kbps = 8
76+
}
77+
78+
public struct Bitrate {
79+
public struct Nominal {
80+
public var brp: UInt16
81+
public var tseg1: UInt16
82+
public var tseg2: UInt16
83+
public var sjw: UInt16
84+
public var sam: UInt8
85+
}
86+
public struct DataPhase {
87+
public var brp: UInt16
88+
public var tseg1: UInt16
89+
public var tseg2: UInt16
90+
public var sjw: UInt16
91+
}
92+
public var frequency: Int32
93+
public var nominal: Nominal
94+
public var data: DataPhase
95+
}
96+
97+
public struct Speed {
98+
public struct Nominal {
99+
public var busSpeed: Float
100+
public var samplePoint: Float
101+
}
102+
public struct DataPhase {
103+
public var busSpeed: Float
104+
public var samplePoint: Float
105+
}
106+
public var nominal: Nominal
107+
public var data: DataPhase
108+
}
109+
```
110+
111+
### DESCRIPTION
112+
113+
CAN API V3 provides the data type [can_bitrate_t](#can_bitrate_t) (**C/C++**) respectively [struct Bitrate](#struct_bitrate) (**Swift**) for adjusting the bit-rate of the CAN controller associated with a CAN channel.
114+
The data types contain the bit-timing settings for Classic CAN operation mode as well as for CAN FD operation mode.
115+
The bit-timing settings are based upon the CAN clock frequency of the CAN controller.
116+
The formula to calculate the bit-rate from frequency-based bit-timing settings is given by [(1)](#formula-1)
117+
and to calculated the sample-point within a bit by [(2)](#formula-2).
118+
119+
Additionally CAN API V3 provides the data type [can_speed_t](#can_speed_t) (**C/C++**) respectively [struct Speed](#struct_speed) (**Swift**) for the data transmission speed (bit-rate in [bit/s]) and the sample-point in Classic CAN operation mode as well as in CAN FD operation mode.
120+
The data transmission speed is a read-only property that cannot be used for adjusting the bit-rate of the CAN controller.
121+
122+
<a id="bitrate_frequency"></a>
123+
Field **frequency** (CAN clock) determines the operating frequency of the CAN controller in hertz (Hz).
124+
It is a crucial parameter as it determines the overall timing and data transmission speed on the CAN bus.
125+
126+
<a id="bitrate_brp"></a>
127+
Field **brp** (bit-rate prescaler) determines the devider of the CAN clock.
128+
The division of the CAN clock by the bit-rate prescaler (BRP) results in the time quanta (TQ).
129+
Time quanta are discrete time intervals used to define various aspects of the bit timing on the CAN bus, such as the length of synchronization segment (SYNC_SEG), propagation segment (PROP_SEG), and phase segments (PHASE_SEG1 and PHASE_SEG2).
130+
The BRP allows for adjusting the bit-rate by dividing the CAN clock frequency accordingly.
131+
132+
<a id="bitrate_tseg1"></a>
133+
Field **tseg1** (time segment 1) determines the length of the first part of the phase segment within a bit time.
134+
Specifically, it sets the duration during which the bit can be changed (dominant to recessive or vice versa) before the sample point.
135+
TSEG1, together with TSEG2, influences the overall bit time and bit-rate.
136+
TSEG1 is equivalent to sum of the propagation segment PROP_SEG and the phase segment PHASE_SEG1.
137+
138+
<a id="bitrate_tseg2"></a>
139+
Field **tseg2** (time segment 2) determines the length of the second part of the phase segment within a bit time.
140+
It defines the time after the sample point where the bit level must remain stable for successful bit reception.
141+
TSEG2 is equivalent to the phase segment PHASE_SEG2.
142+
143+
<a id="bitrate_sjw"></a>
144+
Field **sjw** (synchronization jump width) determines the maximum allowable variation in the synchronization segment (SYNC_SEG) to account for synchronization errors.
145+
In other words, SJW defines how much the bit timing can be adjusted to accommodate variations in clock synchronization between different nodes on the CAN bus.
146+
147+
<a id="bitrate_sam"></a>
148+
Field **sam** (number of samples) determines how many times the CAN controller samples the bus to determine the bit's value during each bit time.
149+
It can be set to either single (1 sample per bit) or triple (3 samples per bit) sampling.
150+
Triple sampling is more robust in noisy environments but requires more processing resources.
151+
It depends on the used CAN controller if triple sampling is sopported.
152+
153+
<a id="bitrate_index"></a>
154+
Field **index** (C/C++ only) determines an index to the [table with predefined bit-timings](#bit-timing-table) (Classic CAN only).
155+
The index to the bit-timing table must be given as a negative value,
156+
or 0 for the bit-rate of 1 MBit/s.
157+
158+
#### CALCULATION OF BIT-RATES :id=formula-1
159+
160+
A bit-rate is calculated according to the following formula:
161+
162+
bit-rate = frequency / (brp * (1 + tseg1 + tseg2))
163+
164+
#### CALCULATION OF SAMPLE-POINTS :id=formula-2
165+
166+
A sample-point is calculated according to the following formula:
167+
168+
sample-point = (1 + tseg1) / (1 + tseg1 + tseg2)
169+
170+
#### BIT-TIMING TABLE
171+
172+
| Index | Bit-rate | Bit time | Sample-point recommendation | Remarks |
173+
| :---- | ---------: | -------: | :-------------------------: | :------ |
174+
| 0 | 1 MBit/s | 1.00 µs | 75% to 90% | |
175+
| 1 | 800 kBit/s | 1.25 µs | 75% to 90% | *Not supported by all devices* |
176+
| 2 | 500 kBit/s | 2.00 µs | 85% to 90% | |
177+
| 3 | 250 kBit/s | 4.00 µs | 85% to 90% | |
178+
| 4 | 125 kBit/s | 8.00 µs | 85% to 90% | |
179+
| 5 | 100 kBit/s | 10.0 µs | 85% to 90% | *Supported for compatibility* |
180+
| 6 | 50 kBit/s | 20.0 µs | 85% to 90% | |
181+
| 7 | 20 kBit/s | 50.0 µs | 85% to 90% | |
182+
| 8 | 10 kBit/s | 100.0 µs | 85% to 90% | |
183+
184+
Bit-timing table according to CiA CANopen specification.
185+
186+
#### BIT-TIMING SETTINGS FOR CAN CONTROLLER SJA1000
187+
188+
| Bit-rate | BRP | TSeg1 | TSeg2 | SJW | SAM | Sample-point |
189+
| ----------: | --: | ----: | ----: | --: | --: | :----------- |
190+
| 1 MBit/s | 1 | 5 | 2 | 1 | 0 | 75.0% |
191+
| 800 kBit/s | 1 | 7 | 2 | 1 | 0 | 80.0% |
192+
| 500 kBit/s | 1 | 13 | 2 | 1 | 0 | 87.5% |
193+
| 250 kBit/s | 2 | 13 | 2 | 1 | 0 | 87.5% |
194+
| 125 kBit/s | 4 | 13 | 2 | 1 | 0 | 87.5% |
195+
| 100 kBit/s | 5 | 13 | 2 | 2 | 0 | 87.5% |
196+
| 50 kBit/s | 10 | 13 | 2 | 2 | 0 | 87.5% |
197+
| 20 kBit/s | 25 | 13 | 2 | 2 | 0 | 87.5% |
198+
| 10 kBit/s | 50 | 13 | 2 | 2 | 0 | 87.5% |
199+
| 5 kBit/s | 64 | 16 | 8 | 2 | 0 | 68.0% |
200+
201+
The CAN controller SJA1000 is running at 8.0 MHz.
202+
203+
#### SYNTAX FOR BIT-RATE STRINGS USED BY CAN API V3 UTILITIES
204+
205+
##### Classic CAN:
206+
f_clock_mhz=<frequency-in-MHz>,nom_brp=<brp>,nom_tseg1=<tseg1>,nom_tseg2=<tseg2>,nom_sjw=<sjw>,nom_sam=<sam>
207+
##### CAN FD:
208+
f_clock_mhz=<frequency-in-MHz>,nom_brp=<brp>,nom_tseg1=<tseg1>,nom_tseg2=<tseg2>,nom_sjw=<sjw>,data_brp=<brp>,data_tseg1=<tseg1>,data_tseg2=<tseg2>,data_sjw=<sjw>
209+
210+
### SEE ALSO
211+
212+
[can_start()](/reference/can_start#can_start) respectively [StartController()](/reference/can_start#startcontroller) \
213+
[can_bitrate()](/reference/can_bitrate#can_bitrate) respectively [GetBitrate()](/reference/can_bitrate#getbitrate) and [GetBusSpeed()](/reference/can_bitrate#getbusspeed)
214+
215+
216+
[copyright](../copyright.md ':include')

0 commit comments

Comments
 (0)