Skip to content

Updated new readme doc with aditional information #6

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

Merged
jdharuman merged 1 commit into from
Jan 8, 2026
Merged

Updated new readme doc with aditional information #6

Show file tree
Hide file tree
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
3 changes: 1 addition & 2 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,5 +43,4 @@ build/
bin/

# Release artifacts
cangaroo-v*.tar.gz
cangaroo-v*.tar.gz.sha256
releases/
57 changes: 37 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,14 @@ Cangaroo is a professional-grade CAN bus analyzer designed for engineers in **Au
---

## 🎥 Demo Gallery
![Cangaroo Trace View](test/trace_view.gif)
*Real-time capture and decoding of CAN traffic using DBC databases.*
<br>![Cangaroo Trace View](test/trace_view.gif)<br>
<!-- slide -->
![Cangaroo Generator View](test/generator_view.gif)
*Simulate CAN traffic with customizable periodic and manual transmissions.*
*Simulate CAN traffic with customizable periodic and manual transmissions.*
<br>![Cangaroo Generator View](test/generator_view.gif)<br>
<!-- slide -->
![Cangaroo Overview](test/output.gif)
*Flexible dockable workspace optimized for multi-monitor analysis.*
<br>![Cangaroo Overview](test/output.gif)<br>

---

Expand All @@ -34,36 +34,37 @@ Cangaroo is a professional-grade CAN bus analyzer designed for engineers in **Au
* **DBC Database Support**: Load multiple `.dbc` files to instantly decode frames into human-readable signals.
* **Data Visualization**: Integrated graphing tools to visualize signal changes over time.
* **Advanced Filtering & Logging**: Isolate critical data with live filters and export captures for offline analysis.
* **Modern Workspace**: A clean, dockable user interface optimized for multi-monitor setups.
* **Modern Workspace**: A clean, dockable userinterface optimized for multi-monitor setups.

---

## 🛠️ Installation & Setup (Linux)

### Option 1: Build from Source
Getting started is as simple as running our automated setup script:

```bash
git clone https://github.com/OpenAutoDiagLabs/CANgaroo.git
cd CANgaroo
./install_linux.sh
```
Follow the interactive menu to install dependencies and build the project.

### Manual Installation
### Option 2: Using Release Package
If you downloaded a pre-compiled release tarball, use the included setup script to prepare your environment:

1. Extract the package: `tar -xzvf cangaroo-vX.Y.Z-linux-x86_64.tar.gz`
2. Run the setup script: `./setup_release.sh`
3. Select an option to install dependencies and/or install Cangaroo to `/usr/local/bin`.

### Manual Dependency Installation

| Distribution | Command |
| :--- | :--- |
| **Ubuntu / Debian** | `sudo apt install qt6-base-dev libqt6charts6-dev libqt6serialport6-dev build-essential libnl-3-dev libnl-route-3-dev` |
| **Fedora** | `sudo dnf install qt6-qtbase-devel qt6-qtcharts-devel qt6-qtserialport-devel libnl3-devel` |
| **Arch Linux** | `sudo pacman -S qt6-base qt6-charts qt6-serialport libnl` |

### Building from Source

```bash
cd src
PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig qmake6
make -j$(nproc)
```

---

## 🚦 Quick Start Guide
Expand All @@ -75,10 +76,22 @@ sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0
```

### 2. Quick Test with Example Data
### 2. Remote CAN Monitoring (SSH Pipe)
Monitor traffic from a remote machine (e.g., a Raspberry Pi on your vehicle) on your local PC:
```bash
# On your local machine, setup vcan0 as shown above, then:
ssh user@remote-ip "candump -L can0" | canplayer vcan0=can0 -t
```
*Now open Cangaroo and connect to `vcan0` to see the remote traffic.*

### 3. ARXML to DBC Conversion
Cangaroo natively supports DBC. If you have ARXML files, you can convert them using `canconvert`:
```bash
# Launch Cangaroo with a virtual interface and fallback DBC
./bin/cangaroo -i vcan0 -d examples/demo.dbc
# Install canconvert
pip install canconvert

# Convert ARXML to DBC
canconvert TCU.arxml TCU.dbc
```

---
Expand All @@ -87,13 +100,17 @@ sudo ip link set up vcan0

Download the latest release tarball from the [Releases Page](https://github.com/OpenAutoDiagLabs/cangaroo/releases).

---

## 🤝 Contribution & Community

### Verifying Your Download
All official releases include a SHA256 checksum. Verify your download using:

```bash
sha256sum cangaroo-v0.4.1-linux-x86_64.tar.gz
sha256sum cangaroo-v0.4.3-linux-x86_64.tar.gz
# Expected output:
# abc123def456... cangaroo-v0.4.1-linux-x86_64.tar.gz
# abc123def456... cangaroo-v0.4.3-linux-x86_64.tar.gz
```

---
Expand All @@ -114,7 +131,7 @@ We welcome contributions!

---

## 📝 Changelog Summary (v0.4.1)
## 📝 Changelog Summary (v0.4.3)
* **Qt 6.10 Migration**: Full support for the latest Qt framework.
* **SocketCAN Stability**: Resolved driver crashes during interface discovery.
* **UI Streamlining**: Removed redundant toggles for a cleaner analysis experience.
Expand Down
13 changes: 9 additions & 4 deletions create_release.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# 1. CHECK INPUT
if [ -z "$1" ]; then
echo "Usage: $0 <version>"
echo "Example: $0 0.4.1"
echo "Example: $0 0.4.3"
exit 1
fi

Expand All @@ -24,28 +24,33 @@ fi

echo "Packaging ${APP_NAME} version ${VERSION}..."

# 3. CREATE STAGING DIRECTORY
# 3. CREATE STAGING AND RELEASE DIRECTORIES
mkdir -p release_stage
mkdir -p releases
cp "$BINARY_PATH" release_stage/
cp README.md release_stage/
cp LICENSE release_stage/
cp CONTRIBUTING.md release_stage/
cp setup_release.sh release_stage/

# 4. CREATE TARBALL
# -C changes directory so the tar doesn't include the 'release_stage' parent folder path
tar -czf "$TAR_FILE" -C release_stage .
tar -czf "releases/$TAR_FILE" -C release_stage .

# 5. GENERATE CHECKSUM
cd releases
sha256sum "$TAR_FILE" > "${TAR_FILE}.sha256"
cd ..

# 6. CLEANUP & OUTPUT
rm -rf release_stage

echo "-------------------------------------------------------"
echo "Release Created Successfully:"
echo "Location: releases/"
echo "Package: $TAR_FILE"
echo "Checksum: ${TAR_FILE}.sha256"
echo "-------------------------------------------------------"
echo "SHA256 Output:"
cat "${TAR_FILE}.sha256"
cat "releases/${TAR_FILE}.sha256"
echo "-------------------------------------------------------"
172 changes: 126 additions & 46 deletions install_linux.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,68 +5,148 @@

set -e

# Setup colors
BLUE='\033[0;34m'
CYAN='\033[0;36m'
GREEN='\033[0;32m'
RED='\033[0;31m'
ORANGE='\033[38;5;208m'
NC='\033[0m' # No Color

# Print ASCII Art
echo -e "${ORANGE}"
echo " ______ ___ _ __ "
echo " / ____// | / | / /____ _ ____ _ _____ ____ ____ "
echo " / / / /| | / |/ // __ \`// __ \`// ___// __ \ / __ \ "
echo "/ /___ / ___ |/ /| // /_/ // /_/ // / / /_/ // /_/ / "
echo "\____//_/ |_/_/ |_/ \__, / \__,_/_/ \____/ \____/ "
echo " /____/ "
echo -e "${NC}"
echo -e "${BLUE}Open-source CAN bus analyzer setup tool${NC}"
echo "-------------------------------------------------------"

# Detect Distribution
if [ -f /etc/os-release ]; then
. /etc/os-release
OS=$ID
else
echo "Unsupported Linux distribution."
echo -e "${RED}Error: Unsupported Linux distribution.${NC}"
exit 1
fi

echo "Detected OS: $OS"
echo -e "Detected OS: ${GREEN}$OS${NC}"

install_deps() {
case $OS in
ubuntu|debian|linuxmint)
echo "Installing dependencies for $OS (using apt)..."
sudo apt update
sudo apt install -y \
build-essential \
qt6-base-dev \
libqt6charts6-dev \
libqt6serialport6-dev \
libnl-3-dev \
libnl-route-3-dev \
libgl1-mesa-dev \
pkg-config \
git
;;
fedora)
echo "Installing dependencies for Fedora (using dnf)..."
sudo dnf install -y \
gcc-c++ \
make \
qt6-qtbase-devel \
qt6-qtcharts-devel \
qt6-qtserialport-devel \
libnl3-devel \
mesa-libGL-devel \
pkgconf-pkg-config \
git
;;
arch)
echo "Installing dependencies for Arch Linux (using pacman)..."
sudo pacman -S --needed --noconfirm \
base-devel \
qt6-base \
qt6-charts \
qt6-serialport \
libnl \
mesa \
pkgconf \
git
;;
*)
echo -e "${RED}Error: Distribution $OS is not explicitly supported by this script.${NC}"
echo "Please install Qt6 (base, charts, serialport) and libnl3 manually."
exit 1
;;
esac
}

build_cangaroo() {
echo -e "${BLUE}Building CANgaroo...${NC}"
cd src
# Try to find qmake6, fallback to qmake if not found or if it's already qt6
QMAKE_CMD=$(command -v qmake6 || command -v qmake)

if [ -z "$QMAKE_CMD" ]; then
echo -e "${RED}Error: qmake not found. Please ensure Qt6 is installed correctly.${NC}"
exit 1
fi

# Set PKG_CONFIG_PATH for ubuntu/debian if needed
if [[ "$OS" == "ubuntu" || "$OS" == "debian" || "$OS" == "linuxmint" ]]; then
export PKG_CONFIG_PATH=/usr/lib/$(uname -m)-linux-gnu/pkgconfig:$PKG_CONFIG_PATH
fi

$QMAKE_CMD
make -j$(nproc)
cd ..
}

install_to_bin() {
echo -e "${BLUE}Installing CANgaroo to /usr/local/bin...${NC}"
if [ -f "bin/cangaroo" ]; then
sudo cp bin/cangaroo /usr/local/bin/
echo -e "${GREEN}Cangaroo installed to /usr/local/bin/cangaroo${NC}"
else
echo -e "${RED}Error: Binary not found at bin/cangaroo. Did the build fail?${NC}"
exit 1
fi
}

echo "Select an option:"
echo "1) Install only dependencies"
echo "2) Install dependencies and build Cangaroo"
echo "3) Install dependencies, build Cangaroo, and install to /usr/local/bin"
read -p "Enter choice [1-3]: " choice

case $OS in
ubuntu|debian|linuxmint)
echo "Installing dependencies for $OS (using apt)..."
sudo apt update
sudo apt install -y \
build-essential \
qt6-base-dev \
libqt6charts6-dev \
libqt6serialport6-dev \
libnl-3-dev \
libnl-route-3-dev \
libgl1-mesa-dev \
pkg-config \
git
case $choice in
1)
install_deps
;;
fedora)
echo "Installing dependencies for Fedora (using dnf)..."
sudo dnf install -y \
gcc-c++ \
make \
qt6-qtbase-devel \
qt6-qtcharts-devel \
qt6-qtserialport-devel \
libnl3-devel \
mesa-libGL-devel \
pkgconf-pkg-config \
git
2)
install_deps
build_cangaroo
;;
arch)
echo "Installing dependencies for Arch Linux (using pacman)..."
sudo pacman -S --needed --noconfirm \
base-devel \
qt6-base \
qt6-charts \
qt6-serialport \
libnl \
mesa \
pkgconf \
git
3)
install_deps
build_cangaroo
install_to_bin
;;
*)
echo "Error: Distribution $OS is not explicitly supported by this script."
echo "Please install Qt6 (base, charts, serialport) and libnl3 manually."
echo -e "${RED}Invalid choice. Exiting.${NC}"
exit 1
;;
esac

echo "-------------------------------------------------------"
echo "Dependencies installed successfully!"
echo "To build CANgaroo, run:"
echo " cd src"
echo " PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig qmake6"
echo " make -j\$(nproc)"
echo -e "${GREEN}Setup completed successfully!${NC}"
if [[ "$choice" -eq 2 ]]; then
echo "You can run CANgaroo from: ./bin/cangaroo"
elif [[ "$choice" -eq 3 ]]; then
echo "You can now run CANgaroo by simply typing 'cangaroo' in your terminal."
fi
echo "-------------------------------------------------------"
Loading