Skip to content

Commit

Permalink
[Meta]: Updated some outdated README info
Browse files Browse the repository at this point in the history
Added missing supported CAN plugins to the list.
Fixed some outdated compilation commands.
Added instructions to acquire Git in addition to CMake, especially for Windows.
Added instructions for how to integrate the library with FetchContent.
Clarified that we don't officially provide precompiled versions of the library.
  • Loading branch information
ad3154 committed Oct 28, 2023
1 parent 96a58c3 commit 1e66fd6
Showing 1 changed file with 57 additions and 13 deletions.
70 changes: 57 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ The library transparently supports the entire ISOBUS/J1939 transport layer, auto
* Virtual Terminal Client (aka Universal Terminal)
* ISOBUS Diagnostic Protocols
* NMEA 2000 Fast Packet
* Common guidance and speed messages

## Getting Started

Expand All @@ -28,13 +29,19 @@ cmake -S . -B build
cmake --build build
```

See the "Integrating this library" section below for how to compile the library as part of a top level application.

### CAN Drivers

A default CAN driver plug-in will be selected for you based on your OS, but when compiling you can explicitly choose to use one of the natively supported CAN drivers by supplying the `CAN_DRIVER` variable.

* `-DCAN_DRIVER=SocketCAN` Will compile with Socket CAN support (This is the default for Linux)
* `-DCAN_DRIVER=WindowsPCANBasic` Will compile with windows support for the PEAK PCAN drivers (This is the default for Windows)
* `-DCAN_DRIVER=MacCANPCAN` Will compile with support for the MacCAN PEAK PCAN driver (This is the default for Mac OS)
* `-DCAN_DRIVER=TWAI` Will compile with support for the ESP TWAI driver
* `-DCAN_DRIVER=TWAI` Will compile with support for the ESP TWAI driver (This is the preferred ESP32 driver)
* `-DCAN_DRIVER=MCP2515` Will compile with support for the MCP2515 CAN controller
* `-DCAN_DRIVER=WindowsInnoMakerUSB2CAN` Will compile with support for the InnoMaker USB2CAN adapter (Windows)
* `-DCAN_DRIVER=TouCAN` Will compile with support for the Rusoku TouCAN (Windows)

Or specify multiple using a semicolon separated list: `-DCAN_DRIVER="<driver1>;<driver2>"`

Expand All @@ -53,47 +60,84 @@ cmake --build build

Tests are run with GTest. They can be invoked through ctest. Once the library is compiled, navigate to the build directory to run tests.
```
cmake -S . -B build -DBUILD_TESTING=ON -DCAN_DRIVER=SocketCAN
cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build
cd build
ctest
```

## Integrating this library

You can integrate this library into your own project with CMake if you want. Adding it as a submodule to your project is one of the easier ways to integrate it today.
You can integrate this library into your own project with CMake if you want. Multiple methods are supported to integrate with the library.

Make sure you have cmake installed:
Make sure you have CMake and Git installed:

Ubuntu
Ubuntu:
```
sudo apt install cmake
sudo apt install cmake git
```

RHEL
RHEL:
```
sudo dnf install cmake
sudo dnf install cmake git
```

Then, submodule the repository into your project:
Windows:

When using windows, the suggested way to get CMake and a working build system is to install [Visual Studio](https://visualstudio.microsoft.com/vs/community/), and select the "Desktop Development with C++" workload as well as `Git` under "Individual Components".

### Git Submodule

Adding this library as a submodule to your project is one of the easier ways to integrate it.

Submodule the repository into your project:

```
git submodule add https://github.com/ad3154/ISO11783-CAN-Stack.git <destination_folder>
git submodule add https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git <destination_folder>
git submodule update --init --recursive
```
Then, if you're using cmake, make sure to add the submodule to your project, and link it.
Then, if you're using CMake, make sure to add the submodule to your project, and link it.
It is recommended to use the ALIAS targets exposed, which all follow the name `isobus::<target_name>`.

```
find_package(Threads)
add_subdirectory(<path to this submodule>)
target_link_libraries(<your executable name> PRIVATE isobus::Isobus isobus::HardwareIntegration isobus::SocketCANInterface)
target_link_libraries(<your executable name> PRIVATE isobus::Isobus isobus::HardwareIntegration isobus::Utility Threads::Threads)
```

A full example CMakeLists.txt file can be found on the tutorial website.

### Integrating with CMake FetchContent

If you don't want to use Git submodules, you can also easily integrate this library and keep it automatically updated by having CMake manage it.

1. Create a folder called `cmake` in your project if you don't already have one.
2. Inside the `cmake` folder, create a file with the following contents:

```
if(NOT TARGET isobus::Isobus)
include(FetchContent)
FetchContent_Declare(
AgIsoStack
GIT_REPOSITORY https://github.com/Open-Agriculture/AgIsoStack-plus-plus.git
GIT_TAG main
)
FetchContent_MakeAvailable(AgIsoStack)
endif()
```

3. In your top-level CMakeLists.txt file, add `list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/cmake)` after your `project` command
4. In your top-level CMakeLists.txt file, add `find_package(AgIsoStack MODULE)` after the above line.
5. Link the library as explained above using `target_link_libraries`

Now when you configure your CMake cache, the library will be pulled from GitHub and automatically made available for your project.

### Precompiled

We do not officially distribute this library in binary form (DLL files, for example).

### Installing The Library

You can also install the library if you want.
Expand All @@ -110,7 +154,7 @@ For a system-wide install:
sudo cmake --install build
```

Then, use a call to find_package() to find this package.
Then, use a call to `find_package()` to find this package.

## Documentation

Expand Down

0 comments on commit 1e66fd6

Please sign in to comment.