ZCLI Hardware Model Upload


EVE-OS Community Supported Hardware Models: A list of community-supported models of hardware that can run EVE-OS is here.

What are they for?

A hardware model identifies resources available on a specific EVE-OS device. A ZEDEDA enterprise administrator can see available resources, and enable or disable their use (by applications). If a particular physical port or resource is excluded from the hardware model it remains “unknown” to EVE-OS, hence it can not be used for app-direct use (aka “PCI passthrough”) and instead gets the default behavior from the Linux kernel. Thus if a VGA interface which is the console when booting is left out of the model, it will continue to show EVE-OS diagnostic output after the install, whereas it wouldn’t be automatically enabled/visible otherwise. A left-out USB port would react to USB memory sticks being inserted automatically. However, EVE-OS can still use network interfaces even if left out of the model because they appear in the "IP link" and will be part of the initial set of interfaces on which EVE-OS runs the DHCP client.

The document below is intended to help you create, test, and upload new hardware models to your ZEDEDA enterprise. The screenshot below shows a couple of examples of hardware models already imported or uploaded into a ZEDEDA enterprise. Note that some models have undergone fairly extensive testing by ZEDEDA, but others perhaps none at all (many are community supported). If you want a specific model fully validated, ask your sales or support contact about getting it on the ZEDEDA Approved Device List (ADL). The ADL models show up in the “available models” section of ZEDEDA production enterprises, whereas those models plus several community-supported models (e.g., Raspberry Pi 4) show up in that section of ZEDEDA Developer Program enterprises.


Creating a New Hardware Model

Creating a new hardware model file is easiest if you install EVE-OS onto the new hardware using the USB installer approach (EVE-OS image version 7.0.0 or later). The installation process will allow you to fetch a template controller-model.json file from the USB stick after the installation is complete. The file will be written to the INVENTORY partition of the USB stick. The name of the folder in that partition is the “soft serial number” -- a unique ID that can be used to onboard the device to ZEDEDA (commercial EVE Controller). Inside that folder will be a few files, one of which is the controller-model.json file. Copy the whole folder onto your computer.


If EVE-OS is already installed, or a version prior to 7.0.0 was installed, you can also run a script at the command line of the EVE-OS edge node, which will generate that same file.

eve exec debug spec.sh > controller-model.json

Copy the resulting file to any USB stick to fetch the same starting point.

Once you have the auto-generated JSON file, you should edit and update it as described in this document:


At a minimum you should:

  • Add a URL pointing to the hardware model specification (online). For example, change line 3 from:
"productURL": "", 


"productURL": "https://ark.intel.com/content/www/us/en/ark/products/126150/intel-nuc-kit-nuc8i3beh.html”
  • Fetch an image of the front and back views of the device, and update the names of the default image files accordingly. For example, update the “logo” section from:


  • Verify CPU core count, main memory, and storage space as per device datasheet
  • Check, test, and update all the physical ports and resources listed in the file, as needed
  • Rename the console-model.json file to include the specific brand and model names, according to the community-supported hardware repository convention. (This is especially important before submitting them as a PR to that repository). For example, change the filename from  controller-model.json to:

for example:


If you would like help submitting your new hardware template and logo files as a PR to be listed among the community-supported models, ask us at dev-program@zededa.com.

Testing a New Hardware Model

Currently, testing must be done manually, and ad hoc according to community documentation. In the future, some automated hardware test tools will be made available from ZEDEDA.

Prerequisites and File Paths

Have a local copy of files be uploaded to ZEDEDA (through ZCLI) in a folder accessible from your home directory. For example, the path to the four files needed might be:

(for macOS => $HOME)


(for Windows => %HOMEPATH%) 


To make sure the docker container running ZCLI will have access to the above files, list them: 

(MacOS): ls $HOME/hw
(Windows): dir %HOMEPATH%/hw

The above commands should show the files you plan to upload through ZCLI.

Note: by using the docker option -v $HOME:/h (MacOS) or -v %HOMEPATH%:/h (Windows) your home directory is mapped to /h, so the full paths to the hardware files from within the container would be:


Running ZCLI to Upload New Hardware Models

Run zcli and configure it to access your ZEDEDA enterprise

docker run -v $HOME:/h -it --rm zededa/zcli:latest (MacOS)
docker run -v %HOMEPATH%:/h -it --rm zededa/zcli:latest (Windows)
zcli> zcli configure
Server [zedcontrol.zededa.net]:  <= just return or override if needed
Login with token?(y/n) [n]: n    <= type n
Username: login@email    <= your ZEDEDA login username
Password:                <= you won’t see *** chars as you type your ZEDEDA password
Output format [text]:    <= just return
zcli> zcli login         <= you need to type this command after above config is done
User <login@email> logged into enterprise: <enterprise_name>.

Check existing brands and models in your ZEDEDA enterprise

zcli brand show
zcli model show

If necessary, add a new or missing brand

zcli brand create <BRAND> --title=<BRAND> --logo=/h/hw/logo_<BRAND>.png

For example:

zcli brand create Intel --title=Intel --logo=/h/hw/logo_Intel.png

Upload validated hardware model files (3 separate commands)

zcli model create <MODEL> --hardware-details=/h/hw/template_l1_MODEL.json --brand=BRAND
zcli model add-artifact MODEL --type=logo1 --file-path=/h/hw/logo_front_MODEL.png
zcli model add-artifact MODEL --type=logo2 --file-path=/h/hw/logo_back_MODEL.png

For example:

zcli model create Intel_NUC8i3BEH --hardware-details=/h/hw/template_l1_Intel_NUC8i3BEH.json --brand=Intel
zcli model add-artifact Intel_NUC8i3BEH --type=logo1 --file-path=/h/hw/logo_front_NUC8i3BEH.png
zcli model add-artifact Intel_NUC8i3BEH --type=logo2 --file-path=/h/hw/logo_back_NUC8i3BEH.png

Check-in your ZEDEDA enterprise Marketplace on the Model tab to see the newly created model.


Exit the ZCLI container at the command shell/prompt.

zcli> exit

Note: don’t worry if you see [Errno 2] as shown below in response to the first model create command because the subsequent “add-artifact” commands will fetch and apply the front and back images. (To add more images, name them with the attribute --type=logoN where N increments for each added image file).

The error that can be ignored:

[Errno 2] No such file or directory: '/workspace/spec/logo_front_NUC8i3BEH.png'
[Errno 2] No such file or directory: '/workspace/spec/logo_back_NUC8i3BEH.png'
Was this article helpful?
2 out of 2 found this helpful