Installation
Windows
- Download the latest elcap-vX.X.X-windows.msi file from the releases page.
- Double click on downloaded file to run the installer.
- Follow the steps in the installer UI.
Linux
- Download the latest elcap-vX.X.X-linux.tar.gz file from the releases page.
- Extract elcap using:
tar -xzf elcap-vX.X.X-linux.tar.gz
- Copy the extracted
elcap binary to your local binary directory: sudo cp elcap /usr/local/bin/
Alternatively, you can add the /path/to/elcap to your .bashrc file by appending export PATH="/path/to/elcap:$PATH" if you want to avoid using sudo.
MacOS
- Download the latest elcap-vX.X.X-macos.zip file from the releases page.
- Extract elcap using:
unzip elcap-vX.X.X-macos.zip
- Copy the extracted
elcap binary to your local binary directory: sudo cp elcap /usr/local/bin/
Alternatively, you can add the /path/to/elcap to your .zshrc file by appending export PATH="/path/to/elcap:$PATH" if you want to avoid using sudo.
First Run
Note: Once a version of the SDK is installed you can create projects from it even if you're not connected to the Internet. You'll need to be online the first time you build a project with that version of the SDK, however, as the Docker image needs to be built. Once the Docker image is built, all subsequent edit/build/flash can happen without an Internet connection.
Once it's in your path, go ahead and run it. You should see something that looks like this.
$ elcap
Downloading v0.3.14 [#################################] 18.12 MiB/18.12 MiB (0s)
Usage: elcap [OPTIONS] COMMAND [ARGS]...
ElCap CLI v0.3.14
Note that you can get help on individual subcommands by appending the
help option:
$ elcap tokens --help
$ elcap tokens write --help
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --verbose -v Enable verbose output │
│ --force-engine [podman|docker] Container Engine [default: None] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ version See version info │
│ doctor Check your environment │
│ flash Flash the specified file or the current project │
│ build Build the current project │
│ clean Delete the current project's build artifacts │
│ new Create a new project │
│ config See or modify elcap's configuration │
│ sdk Install and manage SDK Versions │
│ image Manipulate an existing image │
│ device Interact with a connected device │
│ tokens Configure or modify device tokens │
│ project Configure an existing project │
│ self Manage your ElCap installation │
╰──────────────────────────────────────────────────────────────────────────────╯
Check-in With The Doctor
Next, you can run elcap doctor to check your setup. If you don't already have Docker installed it will let you know.
$ elcap doctor
✅ elcap config should exist
❌ Docker should be installed and in your PATH
🛠 install docker
🛠 confirm docker is in your path
❌ The docker daemon should be running
🛠 Launch Docker Desktop.
🛠 Start the docker service if you're not using Docker Desktop.
❌ JLink v8.10k or newer must be installed
🛠 install the latest jlink tools from: https://www.segger.com/downloads/jlink/
🛠 add the location to your configuration
🛠 Run 'elcap config set tools.jlink_path /path/to/jlink_tools'
✋ Fix the above issues and try again
If you see this, you should install and set up Docker Desktop on your system and make sure it's added to your path. Once that's set up correctly, the doctor will let you know.
$ elcap doctor
Checking your environment...
✅ elcap config should exist
✅ Docker should be installed and in your PATH
✅ The docker daemon should be running
❌ JLink v8.10k or newer must be installed
🛠 install the latest jlink tools from: https://www.segger.com/downloads/jlink/
🛠 add the location to your configuration
🛠 Run 'elcap config set tools.jlink_path /path/to/jlink_tools'
✋ Fix the above issues and try again
Last, but not least, if you would like to flash your project you will need to have the JLink Tools installed. ElCap will automatically include these when you run the doctor command but if this method fails then you can override it using elcap config.
If you are running on Linux, see Linux JLink Installation Requirements below.
$ elcap config set tools.jlink_path "/Applications/SEGGER/JLink_V824"
NOTE: make sure to put quotes around the path if there are any spaces in directory names.
And you can confirm its correct by running config again:
$ elcap config show
tools.jlink_path=/Applications/SEGGER/JLink_V824
Now the doctor should be happy.
$ elcap doctor
Checking your environment...
✅ elcap config should exist
✅ Docker should be installed and in your PATH
✅ The docker daemon should be running
✅ JLink v8.10k or newer must be installed
👍 Looks good!
Installation Troubleshooting
Linux JLink Installation Requirements
Since ElCap does not have sudo permissions, an important file needed by JLink cannot be put into the correct place by ElCap on its own. To solve this problem, follow the below steps:
- Copy the file "99-jlink.rules" from .config/elcap/deps/jlink/x86_64/ to the /etc/udev/rules.d/ directory using this command:
sudo cp ~/.config/elcap/deps/jlink/x86_64/99-jlink.rules /etc/udev/rules.d/
Note: For older systems it might be necessary to replace the "ATTRS" calls in the 99-jlink.rules by "SYSFS" calls
- Either restart your system or manually trigger the new rules with:
sudo systemctl restart systemd-udevd
Creating Your First Project
Our New Project Wizard can walk you through creating a new project.
$ elcap new
Creating a new project...
Project Name: My Awesome Project
name has been set to My Awesome Project
Project Path (my_awesome_project):
path has been set to my_awesome_project
1. v2025.03.00-alpha04
2. v2025.03.00-alpha03
3. v2025.03.00-alpha02
Select SDK Version (1): 1
1. bootloader
2. z-wave
3. zigbee
Select category (1): 3
1. on_off_bulb_zed
2. on_off_switch_szed
3. door_lock_szed
4. empty_zed
Select template (1): 1
1. T32CM11C
Select target (1): 1
******
[project]
name = "My Awesome Project"
category = "zigbee"
target = "T32CM11C"
default_hex = "-neptune-combined.hex"
[sdk]
version = "v2025.03.00-alpha04"
******
Do you confirm generation? [y/n] (y): y
This will create a directory called my_awesome_project in your current directory which will have all the code and information needed to build your project. Take a look at the generated trident.toml file.
$ cat my_awesome_project/trident.toml
[project]
name = "My Awesome Project"
category = "zigbee"
target = "T32CM11C"
default_hex = "-neptune-combined.hex"
[sdk]
version = "v2025.03.00-alpha04"
This directory will have everything elcap needs to build your project, so you can check it into source control and share it with other developers on your team.
Building Your First Project
Make sure you're in the project directory.
Now run the build subcommand.
$ elcap build
...
[100%] Built target my_awesome_project-neptune-combined_hex
[100%] Built target my_awesome_project-custom-combined_hex
That's all there is to it!
Flashing Your First Project
Flashing is (almost) just as easy! First connect your device to your USB port and run:
With only one device connected, the flash command will run automatically for that device. However, if more than one device is connected, you may see something like:
$ elcap flash
Select a device to flash:
1. J-Link-OB-K22-CortexM (USB, Serial: 900040383)
2. J-Link-OB-K22-CortexM (USB, Serial: 900040411)
3. J-Link-OB-K22-CortexM (USB, Serial: 900039517)
Select device to flash (default: 900040383):
Simply select the device you would like to flash to.
What's Next?
Now that you can create, build and flash your project you'll probably want to make it do something interesting. Check out our SDK docs for more information on how to do that.
Need Help?
First, keep in mind that elcap has extensive help menus with more information. For example, try running --help on the flash subcommand.
$ elcap flash --help
Usage: elcap flash [OPTIONS]
Flash the specified file or the current project
╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --usb INTEGER USB serial number of the JLink device (cannot be used with --ip) │
│ [default: None] │
│ --ip TEXT IP address of the JLink device (cannot be used with --usb) [default: None] │
│ --target TEXT flash target │
│ --file PATH file to flash [default: None] │
│ --interface TEXT programming interface [default: SWD] │
│ --speed INTEGER programming speed [default: 4000] │
│ --help Show this message and exit. │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
This will give you details on the available commands and their options.
You can also reach out to us at suppo.nosp@m.rt@t.nosp@m.riden.nosp@m.tiot.nosp@m..com.
1.10.0