https://github.com/haimgel/mqtt2cmd

MQTT to command-line applications gateway
https://github.com/haimgel/mqtt2cmd

Last synced: 21 days ago
JSON representation

MQTT to command-line applications gateway

• Host: GitHub
• URL: https://github.com/haimgel/mqtt2cmd
• Owner: haimgel
• License: apache-2.0
• Created: 2022-10-01T20:10:29.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-04-19T12:35:09.000Z (9 months ago)
• Last Synced: 2024-11-01T01:03:31.938Z (2 months ago)
• Language: Go
• Homepage:
• Size: 124 KB
• Stars: 2
• Watchers: 2
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# MQTT to command-line applications gateway

[![Release](https://img.shields.io/github/release/haimgel/mqtt2cmd.svg?style=flat)](https://github.com/haimgel/mqtt2cmd/releases/latest)

[![Software license](https://img.shields.io/github/license/haimgel/mqtt2cmd.svg?style=flat)](/LICENSE)

[![Build status](https://img.shields.io/github/actions/workflow/status/haimgel/mqtt2cmd/release.yaml?style=flat)](https://github.com/haimgel/mqtt2cmd/actions?workflow=release)

Create virtual MQTT switches from command-line applications. Expose apps running locally on your laptop or desktop to

your home automation server, like [Home Assistant](https://home-assistant.io). 

# Installation

## MacOS

```bash

# Add tap to your Homebrew

brew tap haimgel/tools

# Install it

brew install mqtt2cmd

# Configure (see below for details)

mkdir -p ~/Library/Application\ Support/mqtt2cmd

vi ~/Library/Application\ Support/mqtt2cmd/config.yaml

# Run it in the background, autostart upon boot

brew services start mqtt2cmd

# View the logs

tail -f ~/Library/Application\ Support/mqtt2cmd/mqtt2cmd.log

```

# Configuration

This application expects a configuration file named `config.yaml`, located in:

* `$HOME/Library/Application Support/mqtt2cmd` on MacOS

* `$XDG_CONFIG_HOME/mqtt2cmd` or `$HOME/.config/mqtt2cmd` on Linux

Sample configuration (controls Slack status across multiple Slack workspaces using [slack-status](https://github.com/haimgel/slack-status-go))

```yaml

# Application ID is the prefix for all MQTT topics this app subscribes and publishes to. Defaults to mqtt2cmd

app-id: 'laptop'

mqtt:

  broker: "tcp://your-mqtt-server-address:1883"

switches:

  - name: lunch

    # How often to run the `get_state` command and update the state: useful if the state changes by means

    # other than this application

    refresh: "10m"

    # A command to turn the switch on

    turn_on: "/opt/homebrew/bin/slack-status set lunch"

    # A command to turn the switch off

    turn_off: "/opt/homebrew/bin/slack-status clear"

    # A command to query the state of the switch: exit status = 0 is "ON", exit status = 1 is "OFF"

    get_state: "/opt/homebrew/bin/slack-status -u myteam get lunch"

```

Using the configuration above, `mqtt2cmd` will:

1. Subscribe to MQTT topic `laptop/switches/lunch/set`

2. Publish the current state to `laptop/switches/lunch`

3. Publish overall application availability to `laptop/available`

4. Publish switch availability to `laptop/switches/lunch/available` (will be marked offline if the commands could not be executed successfully).

## Sample Home Assistant configuration

Assuming `mqtt2cmd` is configured as above, the following Home Assistant configuration

will allow to control the virtual "switch" and expose its status and availability.

```yaml

mqtt:

  switch:

    - name: "Slack 'Lunch' status"

      icon: 'mdi:hamburger'

      state_topic: 'laptop/switches/lunch'

      command_topic: 'laptop/switches/lunch/set'

      availability:

        - topic: 'laptop/available'

        - topic: 'laptop/switches/lunch/available'

      availability_mode: 'all'

```