Getting Started

For now¹ a single executable is provided. You can download it from the GitHub Releases page or use the direct links below.

Linux

1. Download and extract the archive and place the ubihome executable in a directory of your choice.

   Devices	Download	Target
   Any Linux	TAR Link	x86_64-unknown-linux-musl
   Raspberry Pi 3	TAR Link	armv7-unknown-linux-musleabi
   Raspberry Pi Zero 2	TAR Link	arm-unknown-linux-musleabi

   # You might have to use a different link from the table above depending on your device type
   curl -L -o ubihome.tar.gz https://github.com/UbiHome/UbiHome/releases/download/v0.14.0/ubihome-Linux-musleabi-armv7.tar.gz
   tar xvzf ./ubihome.tar.gz

2. Edit the configuration file config.yaml in the same directory as the executable. Example:

   config.yaml

   ubihome:
     name: New Awesome UbiHome Device
   
   api:
     encryption:
       key:
   
   shell:
   
   button:
     - platform: shell
       id: my_button
       name: 'Write Hello World'
       command: "echo 'Hello World!' >> test.log"
   
   sensor:
     - platform: shell
       name: 'RAM Usage'
       id: ram_usage
       icon: mdi:memory
       state_class: 'measurement'
       unit_of_measurement: '%'
       update_interval: 30s
       command: |-
         free | grep Mem | awk '{print $3/$2 * 100.0}'

3. Try it out:

   ./ubihome run
   UbiHome - 0.14.0
   LogDirectory: /home/codespace/.local/share
   Config file path: /workspaces/ubihome/config.yaml
   Binary Sensor 'bluetooth_connected' output: false
   Sensor 'ram_usage' output: 38.3144
   Button 'my_button' pressed.
   Command executed successfully with no output.
   # End the process with ctrl+c

4. You should be able to see your device in Home Assistant now.

5. To persistently run the executable install it as a service:

   sudo ./ubihome install
   # The CLI will ask you where to install it. (You can just hit enter to install it in the default location)
   ? Where do you want to install UbiHome? (/usr/bin/ubihome)

   If you do this more often you can add the --install-path flag to the command to specify the path for the installation. Instead of the CLI asking for it.

If you want to uninstall UbiHome you can run the following command:

./ubihome uninstall

Windows

1. Download and extract the archive and place the ubihome executable in a directory of your choice.

   Device	Download	Target
   Windows 11	ZIP Link	x86_64-pc-windows-msvc

   Invoke-WebRequest -OutFile ubihome.zip -Uri https://github.com/UbiHome/UbiHome/releases/download/v0.14.0/ubihome-Windows-msvc-x86_64.zip
   Expand-Archive -Force ubihome.zip ./

2. Edit the configuration file config.yaml in the same directory as the executable. Example:

   config.yaml

   ubihome:
     name: New Awesome UbiHome Device
   
   api:
     encryption:
       key:
   
   shell:
   
   button:
     - platform: shell
       id: my_button
       name: 'Write Hello World'
       command: "echo 'Hello World!' >> test.log"
   
   sensor:
     - platform: shell
       name: 'RAM Usage'
       id: ram_usage
       icon: mdi:memory
       state_class: 'measurement'
       unit_of_measurement: '%'
       update_interval: 30s
       command: |-
         Get-WmiObject Win32_OperatingSystem -Property * | % {([math]::Round(($_.FreePhysicalMemory)/$_.totalvisiblememorysize,2))}

3. Try it out:

   ./ubihome.exe run
   UbiHome - 0.14.0
   LogDirectory: /home/codespace/.local/share
   Config file path: /workspaces/UbiHome/config.yaml
   Binary Sensor 'bluetooth_connected' output: false
   Sensor 'ram_usage' output: 38.3144
   Button 'my_button' pressed.
   Command executed successfully with no output.
   # End the process with ctrl+c

4. You should be able to see your device in Home Assistant now.

5. To persistently run the executable install it as a service:

   Press Windows + X + A for the admin shell.

   ./ubihome.exe install
   # The CLI will ask you where to install it. (You can just hit enter to install it in the default location)
   ? Where do you want to install UbiHome? (C:\Program Files\ubihome)

   If you do this more often you can add the --install-path flag to the command to specify the path for the installation. Instead of the CLI asking for it.

If you want to uninstall UbiHome you can run the following command:

./ubihome.exe uninstall

MacOS

1. Download and extract the archive and place the ubihome executable in a directory of your choice.

   Device	Download	Target
   MacOS (Intel)	TAR Link	x86_64-apple-darwin
   MacOS (Apple Silicon / M series)	TAR Link	aarch64-apple-darwin

   # You might have to use a different link from the table above depending on your device type
   curl -L -o ubihome.tar.gz https://github.com/UbiHome/UbiHome/releases/download/v0.14.0/ubihome-macos-aarch64.tar.gz
   tar xvzf ./ubihome.tar.gz

2. Edit the configuration file config.yaml in the same directory as the executable.

   Check out the entities and platforms we support.

   config.yaml

   ubihome:
     name: New Awesome UbiHome Device
   
   api:
     # encryption:
     #   key:  # Generate here: https://ubihome.github.io/features/connectivity/native_api.html
   
   shell:
   
   button:
     - platform: shell
       id: my_button
       name: 'Write Hello World'
       command: "echo 'Hello World!' >> test.log"
   
   sensor:
     - platform: shell
       name: 'RAM Usage'
       id: ram_usage
       icon: mdi:memory
       state_class: 'measurement'
       unit_of_measurement: '%'
       update_interval: 30s
       command: |-
         free | grep Mem | awk '{print $3/$2 * 100.0}'

3. Try it out:

   ./ubihome run
   UbiHome - 0.14.0
   LogDirectory: /home/codespace/.local/share
   Config file path: /workspaces/ubihome/config.yaml
   Binary Sensor 'bluetooth_connected' output: false
   Sensor 'ram_usage' output: 38.3144
   Button 'my_button' pressed.
   Command executed successfully with no output.
   # End the process with ctrl+c

4. You should be able to see your device in Home Assistant now.

5. To persistently run the executable install it as a service:

   sudo ./ubihome install
   # The CLI will ask you where to install it. (You can just hit enter to install it in the default location)
   ? Where do you want to install UbiHome? (/usr/bin/ubihome)

   If you do this more often you can add the --install-path flag to the command to specify the path for the installation. Instead of the CLI asking for it.

If you want to uninstall UbiHome you can run the following command:

./ubihome uninstall

Footnotes

1. This will change in the future to allow for custom compilation for modular builds and custom extensions. ↩