Contribute a Device Integration Guide

The ThingsBoard documentation website is open source — contributions are welcome. This guide explains how to add a device integration guide and register your hardware in the Hardware Partners directory.

Prerequisites

Before you start, make sure you have:

A GitHub account
Git installed locally
pnpm (the package manager used by this project)

Fork and clone

Open thingsboard/thingsboard.io on GitHub.
Click Fork to create your own copy.
Clone your fork:

git clone https://github.com/YOUR_USERNAME/thingsboard.io.git
cd thingsboard.io

Run the site locally

Install dependencies and start the development server:

pnpm install
pnpm dev

Your local copy of the site is available at http://localhost:4321. File changes reload automatically.

Create the integration guide

1. Add a content file

Create a new MDX file for your guide:

src/content/docs/docs/samples/YOUR_INTEGRATION_NAME/YOUR_GUIDE_NAME.mdx

Use this frontmatter template:

---
title: "YOUR DEVICE — ThingsBoard Integration Guide"
description: Step-by-step guide to connect YOUR_DEVICE to ThingsBoard.
---

Guide content here.

A complete guide typically covers: prerequisites, device provisioning in ThingsBoard, connection setup, data mapping, and a sample dashboard.

2. Add images

Store screenshots and diagrams under:

src/assets/images/samples/YOUR_INTEGRATION_NAME/

Reference them in your MDX with the ImageGallery component:

import ImageGallery from '~/components/ImageGallery.astro';

<ImageGallery images={[
  {
    src: '/src/assets/images/samples/YOUR_INTEGRATION_NAME/setup.png',
    alt: 'Connection diagram',
  },
]} />

Register as a hardware partner

Add an entry to src/data/partners/hardware-partners.ts:

{
  name: "Your Company Name",
  slug: "your-company-slug",
  connectivity: ["MQTT", "HTTP"],
  industry: ["Smart Buildings"],
  useCase: ["Energy Monitoring"],
  hardwareTypes: ["Sensors"],
  logo: "/images/partners/your-logo.webp",
  website: "https://www.your-company.com/",
  links: {
    sensorGuides: [
      {
        label: "Your Device — ThingsBoard Integration Guide",
        href: "/docs/samples/YOUR_INTEGRATION_NAME/YOUR_GUIDE_NAME/"
      }
    ]
  },
  description: "Brief description of your company and product line."
}

Place your company logo (WebP format, minimum 200×200 px) at:

public/images/partners/your-logo.webp

The links object supports these guide categories: sensorGuides, gatewayGuides, generalGuides, microcontrollersGuides, singleBoardComputersGuides, trackersGuides, and otherGuides. Use whichever fits your hardware type.

Submit changes

When your guide is ready, push to your fork and open a pull request against the main branch. The full push-and-PR workflow — including the CLA signing step — is covered in the Contribution Guide.