Forem: Allen Tuh

How to Use Sidekick's Instant Commands from OpenAPI/Postman

Allen Tuh — Mon, 23 Mar 2026 15:49:25 +0000

Sidekick (sdkck) is a CLI companion tool designed for AI agents and developers. One of its most powerful features is the ability to turn any OpenAPI/Swagger spec or Postman collection into executable CLI commands — instantly. No code generation, no SDK wrappers. Just point it at a spec, and every endpoint becomes a command you can run.

This guide walks you through the full workflow: importing specs, calling endpoints, configuring auth, searching commands, and managing your imported APIs.

Prerequisites

Install Sidekick globally via npm:

npm install -g sdkck

Step 1: Import an OpenAPI Spec or Postman Collection

The sdkck openapi import command accepts a URL or a local file path. It parses the spec and registers every operation as a runnable CLI command.

From a URL:

sdkck openapi import https://raw.githubusercontent.com/upstash/context7/refs/heads/master/docs/openapi.json --name context7

The --name flag gives your API a short identifier that becomes the command namespace. If you omit it, Sidekick derives a slug from the spec's title.

You can also configure auth and a custom base URL during import:

sdkck openapi import ./api.yaml --name myapi --auth-type bearer --token sk-... --base-url https://api.example.com

Step 2: List and Call Operations

Once imported, use sdkck <API name> to see all registered operations:

Use --help to see the details how to use an operation

Step 3: Configure Authentication

Most real APIs require authentication. Sidekick supports three auth types, configured once per API so every subsequent command uses it automatically.

Bearer token:

sdkck openapi auth petstore --type bearer --token sk-your-token-here

API key:

sdkck openapi auth myapi --type apikey --api-key mykey123 --api-key-header X-API-Key

Basic auth:

sdkck openapi auth petstore --type basic --username user --password secret

Verify your auth settings:

sdkck openapi auth petstore --show

To remove auth from an API:

sdkck openapi auth petstore --type none

Step 4: Update API Configuration

After importing, you can modify the API's settings without re-importing:

# Change the base URL (e.g., switch from staging to production)
sdkck openapi config petstore --base-url https://api.mypetstore.com/v2

# Rename the API namespace
sdkck openapi config petstore --rename mystore

# Update the display title and description
sdkck openapi config petstore --title "My Petstore" --description "Internal pet store API"

Step 5: Remove an API

When you no longer need an imported API:

sdkck openapi remove context7

This unregisters all the operations associated with that spec.

Setup Permissions

You can lock down agent permissions for safety:

# Allow only read operations
sdkck permission allow "petstore listPets"
sdkck permission allow "petstore getPetById"
sdkck permission disallow "petstore *"

# Export permissions for team sharing
sdkck permission export permissions.json

Quick Reference

Task	Command
Import a spec	`sdkck openapi import <source> --name <name>`
List all APIs	`sdkck openapi list`
List operations	`sdkck <API name> --help`
Configure auth	`sdkck openapi auth <name> --type bearer --token <token>`
Update config	`sdkck openapi config <name> --base-url <url>`
Remove an API	`sdkck openapi remove <name>`

Summary

Sidekick's OpenAPI/Postman import feature eliminates the gap between having an API spec and being able to use it. There's no code to write, no SDK to learn. Import the spec, configure auth once, and every endpoint is immediately callable from the command line — by you or by an AI agent. Combined with semantic search and a permission system, it makes any API accessible in seconds.

For more details, visit the Sidekick GitHub repository.

Getting Started with Sidekick (sdkck): A Complete Setup Guide

Allen Tuh — Tue, 17 Mar 2026 07:26:12 +0000

How to install the agentic CLI and connect it to Jira, MySQL, Sentry, and more

Sidekick (sdkck) is an agentic CLI that supercharges your terminal with a growing library of tools delivered via plugins. Whether you're managing Jira tickets, querying databases, or triaging Sentry errors — Sidekick brings it all into one place without leaving your command line.

This guide walks you through installing Sidekick and configuring authentication for three of the most commonly used integrations: Jira, MySQL, and Sentry.

Prerequisites

Node.js v20 or later
npm installed globally
Terminal access (macOS, Linux, or WSL on Windows)

Step 1: Install Sidekick

npm install -g sdkck

Verify the installation:

sdkck --version
# sdkck/0.4.0 linux-x64 node-v20.20.0

To see all available commands at any time:

sdkck --help
sdkck commands

Step 2: Official Plugins — Already Included

No need to hunt for third-party packages. Sidekick ships with a suite of official @hesed plugins that are preinstalled out of the box:

Plugin	What it connects to
`@hesed/jira`	Atlassian Jira
`@hesed/sentry`	Sentry error monitoring
`@hesed/mysql`	MySQL databases
`@hesed/psql`	PostgreSQL databases
`@hesed/supabase`	Supabase database
`@hesed/conni`	Connection manager
`@hesed/bb`	Bitbucket

These are bundled with your sdkck installation — you do not need to run plugins add for any of them. They are available immediately after installing Sidekick.

To confirm they are present:

sdkck plugins --core

You should see all @hesed/* plugins listed under core plugins.

Installing Additional Plugins

If you need integrations beyond the official set, Sidekick's plugin system is fully open. Install any compatible plugin from the npm registry:

sdkck plugins add <plugin-name>

To update all plugins (official and user-installed):

sdkck plugins update

Tip: Use sdkck search <query> to discover available commands across all installed plugins.
sdkck search jira
sdkck search "create issue"

Step 3: Connecting Jira/Confluence/Bitbucket

The @hesed/jira plugin is preinstalled — no setup needed on the plugin side. All you need is your Atlassian API token.

Retrieve Your Jira API Token

Jira uses API tokens (not passwords) for CLI and third-party authentication.

Log in to your Atlassian account at https://id.atlassian.com
Click your profile avatar in the top-right corner
Select "Account settings"
Navigate to the "Security" tab
Under "API token", click "Create and manage API tokens"
Click "Create API token"
Give it a descriptive label (e.g., sdkck-cli) and click "Create"
Copy the token immediately — it won't be shown again

Configure Jira Auth in Sidekick

Once you have your token, configure your Jira credentials. The exact command depends on your installed plugin, but the standard pattern is:

sdkck jira auth add

Step 4: Connecting MySQL/PostgreSQL

The @hesed/mysql and @hesed/psql plugins are preinstalled. All you need are your database credentials.

MySQL/PostgreSQL authentication in Sidekick uses standard database credentials. You can connect to a local or remote instance.

Retrieve Your MySQL/PostgreSQL Credentials

You'll need the following from your database administrator or cloud provider:

Field	Example
Host	`db.yourcompany.com` or `localhost`
Port	`3306`
Database	`production_db`
Username	`sdkck_user`
Password	`your_db_password`

Configure MySQL Auth in Sidekick

sdkck mysql auth add

Security tip: For production environments, use a read-only database user for Sidekick to limit blast radius if credentials are ever exposed.

Step 5: Connecting Sentry

The @hesed/sentry plugin is preinstalled. Sentry uses Auth Tokens for API access — scoped tokens that can be granted specific permissions.

Retrieve Your Sentry Auth Token

Log in to https://sentry.io
Click your username/avatar in the bottom-left sidebar
Select "User Auth Tokens" (or navigate to Settings → Account → API → Auth Tokens)
Click "Create New Token"
Give it a name (e.g., sdkck-cli)
Select the required scopes — at minimum:
- project:read
- event:read
- org:read
Click "Create Token"
Copy the token immediately

Configure Sentry Auth in Sidekick

sdkck sentry auth add

Putting It All Together

Once your integrations are configured, you can start using Sidekick's full power. Use search to discover what commands are available across your plugins:

# Find all Jira-related commands
sdkck search jira

# Find commands with full help output
sdkck search sentry -d

# Find database query commands
sdkck search "mysql query" --details

Example Workflow

# List open Jira issues assigned to you
sdkck jira issues --assignee me --status "In Progress"

# Run a quick MySQL query
sdkck mysql query "SELECT COUNT(*) FROM users WHERE created_at > NOW() - INTERVAL 7 DAY"

# Check the latest Sentry errors in a project
sdkck sentry issues --project my-backend --limit 10

Managing Your Plugins

Task	Command
List installed plugins	`sdkck plugins`
Add a plugin	`sdkck plugins add <name>`
Update all plugins	`sdkck plugins update`
Remove a plugin	`sdkck plugins remove <name>`
Reset all plugins	`sdkck plugins reset`
Inspect a plugin	`sdkck plugins inspect <name>`

Keeping Sidekick Updated

npm update -g sdkck

Security Best Practices

Never commit API tokens to version control. Use .env files with .gitignore, or a secrets manager like 1Password CLI or AWS Secrets Manager.
Use the minimum required scopes. When creating tokens for Jira and Sentry, only grant the permissions Sidekick actually needs.
Rotate tokens regularly. Treat CLI tokens the same way you'd treat production secrets.
Use read-only database credentials for MySQL unless your workflow explicitly requires write access.

Troubleshooting

Plugin not found after install:

sdkck plugins reset
sdkck plugins add <plugin-name>

Auth errors with Jira:

Double-check that your JIRA_DOMAIN includes https:// and ends without a trailing slash
Ensure the API token belongs to an account with access to the target project

MySQL connection refused:

Verify the host allows connections from your IP (check firewall/security group rules)
Confirm the port is correct (default 3306)

Sentry token permission error:

Re-check that the token scopes include project:read and event:read
Confirm the --org slug matches exactly what appears in your Sentry URL

What's Next?

You've configured the most common integrations, but Sidekick ships with even more out of the box. The other preinstalled @hesed plugins follow the same auth pattern — grab a credential from the provider dashboard and pass it in:

@hesed/supabase — uses your Supabase project
@hesed/bb — connects to Atlassian Bitbucket
@hesed/conni — connects to Atlassian Confluence

For any of these, use sdkck search <plugin-name> -d to see the full list of available commands and flags.

Sidekick is built to grow further. The plugin architecture means new community integrations can be added without touching the core CLI. Keep an eye on the npm registry for new plugin releases, and use sdkck search to explore everything already available.

Happy building. 🛠️

Why I Switched from MCP to CLI

Allen Tuh — Tue, 17 Mar 2026 00:38:43 +0000

After months wrestling with bloated context windows and flaky protocol servers, I went back to basics — and my AI coding agent finally started working the way I wanted.

I was the MCP evangelist in my team. I set up the Atlassian MCP server, the Playwright MCP, the Figma MCP and much more. Then I started actually using them with Claude Code on a real project.

I keep hitting the limit on Claude Pro plan with just a few round of prompting. I check the token counter and found out that all the MCP servers have took up almost 40% to 50% of the context window before the agent did a single useful thing!

That was the moment I uninstalled everything and opened a terminal.

The MCP promise vs. the MCP reality

Model Context Protocol arrived in late 2024 with enormous backing. Every major AI provider endorsed it. The pitch was clean: one standard protocol, any AI model, any tool. Build an MCP server for your database and every AI client could query it. No more per-client glue code.

In theory, beautiful. In practice, the seams show quickly.

What actually happens when MCP loads

A standard Atlassian MCP server dumps its entire tool schema into your context window on initialization — all 73 tools, their parameter descriptions, authentication flows, state management instructions. Your agent hasn't done anything yet, and roughly 40% of your context budget is already gone.

The deeper problem is architectural. MCP asks AI models to operate through an abstraction layer they were never trained on. Claude, GPT-4, Gemini — these models have been trained on billions of lines of terminal interactions. Stack Overflow answers, GitHub READMEs, documentation, tutorials — all of it is saturated with shell commands. They know git, gh, docker, kubectl as fluently as a senior engineer who's been at the terminal for a decade.

MCP schemas? Zero training data. The model is improvising every time.

Why CLI wins for developer workflows

Self-documenting by design. Every CLI tool ships with --help and man pages. The agent can explore what a command does, drill into subcommands, and discover options — all without an external schema definition. No MCP server to maintain, no schema to keep in sync.

Composability built over 50 years. Unix pipes. Output routing. Chaining. Parallel execution with && and ||. MCP is designing in 2025–2026 what Unix figured out in the 1970s and spent five decades debugging. CLI composability carries the reliability of a v50 system. MCP composability is v0.1.

LLMs just know this stuff. The model has seen find . -name "*.ts" | xargs grep "import" ten thousand times. It improvises novel combinations because the composability grammar is embedded in its weights. When it hits an error, it knows how to parse stderr, adjust flags, and retry. That fluency simply doesn't exist for MCP tool chains.

"Tool results and definitions can sometimes consume 50,000+ tokens before an agent reads a request... At Anthropic, we've seen tool definitions consume 134K tokens before optimization." - Anthropic Engineering Blog

"Previously, the Projects toolset, as with other now-consolidated toolsets, used a significant portion of the context window for the tools list. As a result, we've reduced token usage by around 23,000 tokens (50%)." - GitHub Changelog

"MCP were a mistake. Bash is better." - Peter Steinberger, creator of OpenClaw

Introducing Sidekick

This brings me to a project I've been using heavily: Sidekick (sdkck). It's an open-source agentic CLI built to give AI coding agents like Claude Code a clean, composable, extensible interface to the tools they need — without the MCP overhead.

hesedcasa / sdkck

Agentic CLI that provides multiple tools via plugins

 ____  _     _      _    _      _
/ ___|(_) __| | ___| | _(_) ___| | __
\___ \| |/ _` |/ _ \ |/ / |/ __| |/ /
 ___) | | (_| |  __/   <| | (__|   < 
|____/|_|\__,_|\___|_|\_\_|\___|_|\_\

Sidekick (sdkck)

The Best Companion Tool for AI Agents

One CLI to search, connect, and command every tool in your stack. Zero context window bloat. Maximum productivity.

Key Features

Instant Commands from OpenAPI/Postman

Point Sidekick at any OpenAPI/Swagger spec or Postman collection — local file or URL — and every endpoint becomes a CLI command instantly.

# Import an OpenAPI spec from a URL or local file
sdkck openapi import https://petstore3.swagger.io/api/v3/openapi.json --name petstore
# Import a Postman collection the same way
sdkck openapi import ./postman_collection.json --name myapi

# Every operation is now a real command
sdkck petstore listPets
sdkck petstore getPetById --param petId=42
sdkck petstore createPet --body name=Fido --body tag=dog

…

View on GitHub

What makes Sidekick interesting isn't just what it does — it's how it fits into AI-first workflows. Because it's a standard CLI, Claude Code and other agents can discover its capabilities naturally:

# Agent discovers available commands
sdkck --help

# Search for specific functionality
sdkck search "create pr"
sdkck search "jira" -d
sdkck search "update issue" --details

The search command is the key insight. Instead of dumping your entire tool catalogue into context, an agent can query for exactly what it needs in the moment. This is context efficiency by design.

Using Sidekick with Claude Code

Here's how to set this up. First, install Sidekick and any plugins your workflow needs:

# Install Sidekick globally
npm install -g sdkck

# Install plugins (community or your own)
sdkck plugins add myplugin
sdkck plugins add someuser/someplugin

# Verify installation
sdkck version

Then document it in your CLAUDE.md at the project root. This is the equivalent of an MCP server config — except it costs zero tokens at load time:

# CLAUDE.md

## Available CLI Tools

sdkck is installed and available. Use it for task and issue management.

### Discovery
sdkck search "<query>"          # find relevant commands
sdkck search "<query>" -d       # detailed help for each result
sdkck --help                     # full command list

### Workflow
Always search before assuming a command exists.
Prefer composing sdkck commands with standard Unix pipes.

When Claude Code encounters a task, it searches first, then acts. Here's what that looks like in practice:

# Claude Code working on a feature branch

# 1. Search for relevant commands
sdkck search "create pr" --details

# 2. Compose with existing tools
gh pr create --title "feat: add auth" --body "$(cat PR_TEMPLATE.md)"

# 3. Chain with other commands naturally
sdkck search "jira" | head -5

Extending Sidekick with Plugins

The plugin system is where Sidekick becomes genuinely powerful. You can build and link your own tools for development:

# Install a plugin from a github url.
sdkck plugins install https://github.com/someuser/someplugin

# Inspect what got installed
sdkck plugins inspect my-jira-plugin

# List all installed plugins
sdkck plugins

# Keep plugins updated
sdkck plugins update

For other coding agents — Cursor, Copilot, Kiro, OpenClaw — the integration pattern is the same: document Sidekick in whatever context file the agent reads (AGENT.md, .cursorrules, agent instructions), and let the agent discover capabilities through sdkck search rather than preloading schemas.

The Honest Nuance

I want to be fair here: MCP isn't bad. It has a legitimate use case, and writing it off entirely would be intellectually dishonest.

For 80–90% of developer-facing use cases — building features, running tests, managing git, automating your own workflows — CLI is the faster, cheaper, more reliable path. For multi-tenant products where your agent acts on behalf of customers inside their organizations, MCP's governance model earns its overhead.

The smartest teams in 2026 aren't picking sides. They're using CLI for development workflows and MCP for customer-facing compliance-sensitive features. But if you're a developer automating your own stack, there's no reason to carry MCP's weight.

Getting started

If you want to try this approach today:
Detail guide can be found here

# Install Sidekick
npm install -g sdkck

# Explore what's available
sdkck commands
sdkck search "anything"

# In your project root
echo "sdkck is available. Use 'sdkck search <query>' to find commands." >> CLAUDE.md

That's it. No JSON config. No SSE server. No schema dumped into your context. Just a tool your agent can pick up and use.

The Unix philosophy — small, composable tools that do one thing well — has proven remarkably durable. Fifty years later, it turns out it's also the best interface we've built for AI agents. Not because we planned it that way. Because we already spent fifty years making it work.

Using Claude Code with GitHub Copilot Subscription

Allen Tuh — Wed, 22 Oct 2025 06:24:17 +0000

Do you have a Github Copilot subscription sitting around doing nothing? Why not pair it with the Claude Code (claimed by many developers as the best AI coding agent thus far).

A. Using LiteLLM

Install Python on your local machine
Setup LiteLLM
Create a folder for LiteLLM e.g.: litellm
Create a config.yaml file with the below content in the litellm folder

model_list:
  - model_name: anthropic/*
    litellm_params:
      model: github_copilot/gpt-5-mini
      extra_headers: {"editor-version": "vscode/1.85.1", "Copilot-Integration-Id": "vscode-chat"}
  - model_name: anthropic/*
    litellm_params:
      model: github_copilot/claude-sonnet-4.5
      extra_headers: {"editor-version": "vscode/1.85.1", "Copilot-Integration-Id": "vscode-chat"}

Start the litellm proxy server

litellm --config config.yaml

B. Using Copilot API

First you need to setup GitHub Copilot API proxy
Run npm install -g copilot-api to install the API proxy
Run copilot-api start to start the proxy server

Setup Claude Code

Now install Claude Code in your local machine
Run npm install -g @anthropic-ai/claude-code
Edit the config file .claude/settings.json for Claude Code to use the LiteLLM or Copilot API proxy server instead of the default Claude subscription which is more expensive
Add this settings into the config file

LiteLLM

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://0.0.0.0:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key",
    "ANTHROPIC_MODEL": "github_copilot/claude-sonnet-4.5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "github_copilot/gpt-5-mini",
    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Copilot API

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4141",
    "ANTHROPIC_AUTH_TOKEN": "sk-dummy",
    "ANTHROPIC_MODEL": "claude-sonnet-4.5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5-mini",
    "DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

Start your Claude Code and enjoy coding!

I hacked Sonoff RF Bridge to control my ceiling fan lights

Allen Tuh — Mon, 20 Oct 2025 08:03:19 +0000

I have the Home Assistant setup in my house. I installed 4 ceiling fan lights in my house. Each ceiling fan light is connected to a smart switch. However, only the light will turn on when I turn on the switch. To turn on the fan, I need to use the remote control. This isn't very pleasant for a person who likes conveniences such as me.

I must do something to satisfy my "laziness". Basically to be able to control the ceiling fan light, first, you need to find out the RF signals the remote control sends to the ceiling fan lights, then you need to be able to replicate these RF signals via other means or hardware. I came across a few solutions:

A. Duplicate the remote control circuit

This solution involves opening up my current remote controller to decode the RF signal used to control the fan, which is a NO-NO for me because my remote controller is sealed tight. I also do not have the resources to build a circuit board. However, if you are interested you can refer to this video tutorial.

B. Replace with Tuya WiFi smart remote control kit

This solution is more straightforward. You just need to buy a new remote control kit here. Tuya allows you to integrate directly with Home Assistant. Since my fans are new and I don't want to break my warranty, I will skip this solution.

C. Install Sonoff RF bridge

This solution is very challenging and has a lot of roadblocks. I was not aware of what I was getting myself into. Initially, I thought I just going to buy and install a Sonoff RF bridge and I am done. Boy, I was so wrong!

Journey to hack the Sonoff RF bridge

Sonoff RF bridge was only compatible with the Sonoff family of RF devices, so no luck with my ceiling fan lights. However, I came across several projects that hack the Sonoff RF bridge to work with more RF devices. These projects give me hope. I tried every single one of them and finally made one of them work with my ceiling fan lights. I will list down all the relevant projects, but will only emphasize the one that work for me.

OMG! It works!

After countless weeks of trying, I finally got OMG(OpenMQTTGateway) to work on the Sonoff RF bridge and control all my ceiling fan lights from Home Assistant. Here is the step-by-step guide:

Prerequisite

Sonoff RF Bridge
USB to serial adapter (for flashing firmware)
Software-Defined Radio(SDR) (to decode the RF signal)
Soldering kit
Some programming knowledge

1. Hack the PCB board

If you bought a Sonoff RF bridge from the Internet, most likely it will be version R2 V2.2. If you have other versions, please refer here. Solder a jumper from the pin USBRXD to the target pin of the receiver chip and another one from the pin USBTXD to the target pin of the transmitter chip as shown in the photo below. I get the circuit modification from here.

Flip to the back side of the PCB and cut off the traces at the 2 points shown in the photo below.

2. Create the custom firmware

Obviously, we are going to load the OMG firmware. As of the moment only v0.9.16 works. Check out the v0.9.16 of the OMG repo from https://github.com/theengs/OpenMQTTGateway. OMG is developed with PlatformIO so setup your IDE accordingly (https://platformio.org/platformio-ide).
Create a prod_env.ini file to be able to connect to the house WiFi network and talk to the Home Assistant via MQTT protocol. Here is the example file I created.

[platformio]
default_envs = rfbridge-direct-1

[env:rfbridge-direct-1]
platform = ${com.esp8266_platform}
board = esp8285
lib_deps =
  ${com-esp.lib_deps}
  ${libraries.wifimanager8266}
  ${libraries.esppilight}
build_flags =
  ${com-esp.build_flags}
  '-DZgatewayPilight="Pilight"'
  '-DRF_RECEIVER_GPIO=4'
  '-DRF_EMITTER_GPIO=5'
  '-DLED_INFO=13'
  '-DLED_INFO_ON=0'
  '-DZsensorGPIOInput="GPIOInput"'
  '-DINPUT_GPIO=0'
  '-fcommon'
  '-DESPWifiManualSetup=true'
  '-DGateway_Name="OMGSonoff"'
  '-Dgw_password="password"'
  '-Dwifi_ssid="MYWIFI"'
  '-Dwifi_password="password"'
  '-DNetworkAdvancedSetup=true'
  '-DNET_IP="192.168.1.605"'
  '-DNET_MASK="255.255.255.0"'
  '-DNET_GW="192.168.1.254"'
  '-DBase_Topic="omgsonoff/"'
  '-DMQTT_USER="mqtt-user"'
  '-DMQTT_PASS="password"'
  '-DMQTT_SERVER="192.168.1.501"'
board_build.flash_mode = dout
board_build.ldscript = eagle.flash.1m64.ld ;this frees more space for firmware upload via OTA.
custom_description = RF gateway for the Sonoff RF Bridge requiring direct hack, relying on ESPilight library, [tutorial](https://1technophile.blogspot.com/2019/04/sonoff-rf-bridge-pilight-or-how-to.html).
custom_hardware = RFBridge v1

Change the below settings accordingly:

Dwifi_ssid: your house's WiFi SSID
Dwifi_password: WiFi password
DNET_IP: Static IP for the Sonoff RF Bridge
DNET_MASK: Subnet mask
DNET_GW: Gateway IP
DMQTT_USER: MQTT user created in Home Assistant
DMQTT_PASS: MQTT user password
DMQTT_SERVER: MQTT server usually is the IP for your Home Assistant

After successfully building the OMG project, you will get the firmware file.

3. Flash the firmware

Sonoff is using the ESP8266 chip which makes flashing custom firmware possible. Solder 4 headers to the 4 programming pins on the PCB. Connect the serial adapter to the programming headers as shown below: Always ensure that the voltage setting on the adapter is 3.3V.

Download and install the ESPTool. Make a backup of the original firmware by running this command:

esptool.py --port /dev/cu.usbserial-21420 read_flash 0x00000 0x100000 esp-1MB-backup.bin

Clear the firmware on the chip by running this command:

esptool.py erase_flash

Flash the custom firmware to the chip by running this command:

esptool.py --chip esp8266 --port /dev/cu.usbserial-21420 write_flash --flash_size detect --flash_mode dout 0x00000 firmware.bin

You can refer to this video tutorial. Plug in the Sonoff RF Bridge to the power supply and you should see the blue LED turn on.

4. Connect OMG to Home Assistant via MQTT

Install MQTT and Mosquitto broker add-on in Home Assistant. I will not go through the process here. Create the MQTT user in Home Assistant to allow OMG to connect to the Home Assistant with this user. The username and password MUST match the one we set in Step 2.

If everything is setup correctly, you will see this in the Mosquitto broker log.

5. Hack the ceiling fan light RF signal

Plug in the SDR into your Laptop and install Universal Radio Hacker (URH) software. Get your ceiling fan light remote control ready and record the RF signal with URH. Usually, the RF frequency is 433.92M.