HummingBird IoT Development Platform

HummingBird (蜂鸟) is an ultra-lightweight IoT (Internet of Things) development platform implemented in Golang. It is designed for high performance and low memory footprint.

Key characteristics include:

• High Performance: Can support thousands of device connections and millions of messages on minimal hardware (e.g., 1C/1G RAM can handle thousands of devices and 80M messages).
• Flexible Storage: Uses SQLite and LevelDB by default for lightweight, high-throughput, and high-compression storage. For large-scale or high-reliability requirements, it supports swapping to MySQL and TDengine.
• Comprehensive IoT Features: Includes device access, product management, Thing Model (物模型), alarm centers, and rule engines.

HummingBird provides a full suite of IoT management capabilities:

• Management: Product management, Device management, Image management, and Driver management.
• Extensibility: Driver market, Plugin market, and Scene linkage (场景联动).
• Intelligence & Monitoring: Rule engine, Alarm center, System monitoring, and Data dashboards (可视化大屏).
• Resource Management: General resource management and driver market access.

To contribute to the project, follow these workflow steps:

1. Ensure your local master branch is up to date.
2. Create a new branch from master using the format feature/username/description (e.g., feature/pick/mqtt_driver).
3. Edit documentation or code and commit your changes.
4. Submit a Pull Request (PR) to the develop branch. Wait for the author to review and merge.

You can deploy HummingBird quickly using Docker Compose. Follow these steps to clone the repository and start the services in detached mode:

1. Clone the repository:

   git clone https://gitee.com/winc-link/hummingbird.git

2. Navigate to the Docker manifest directory:

   cd hummingbird/manifest/docker

3. Start the services:

   docker-compose up -d

The WeixinClient generates different markdown templates depending on the Trigger type defined in the models.Rule. The supported triggers are:

1. constants.DeviceDataTrigger: Used for data-driven alerts (e.g., a specific property value exceeding a threshold). The template includes the device name, rule name, property name (with code), current value, and timestamp.
2. constants.DeviceEventTrigger: Used for event-based alerts. The template includes the device name, rule name, event name (with code), event content (if available), and timestamp.
3. constants.DeviceStatusTrigger: Used for device status changes. The template includes the device name, rule name, and the current device status.

Most administrative and sensitive endpoints (like POST /api/v1/product or GET /api/v1/homepage) require authentication.

Authentication is performed by providing a token in the request header:

• Header Name: x-token
• Type: apiKey

GET /api/v1/homepage
x-token: YOUR_ACCESS_TOKEN

The WebSocket server communicates using specific JSON structures for incoming and outgoing messages.

Incoming Message (WsData)

When a client sends a message, it is expected to follow the WsData structure (unmarshaled in readPump):

• Code: The identifier for the requested action.
• Data: The payload associated with the action.

Outgoing Message (WsResponse)

When the server sends a message, it uses the WsResponse structure:

• Code: The dtos.WsCode identifying the response.
• Data: An httphelper.CommonResponse containing:
  • Success: Boolean indicating if the operation succeeded.
  • ErrorCode: The error code if Success is false.
  • ErrorMsg: A localized error message (automatically translated if Success is false and ErrorCode is provided).
  • The actual data payload if Success is true.

The API uses ApiKeyAuth for security. You must include a token in the request header.

Header Key: x-token

To use the MySQL database connectivity in Hummingbird, use the NewClient function. It requires a dtos.Configuration object and a logger.LoggingClient. The function returns a pointer to a Client and an error if initialization fails.

Note: The Client struct provides access to a Pool which is a *gorm.DB instance, allowing you to perform direct GORM operations if needed.

import (
	"github.com/winc-link/hummingbird/internal/dtos"
	"github.com/winc-link/hummingbird/internal/pkg/logger"
	"github.com/winc-link/hummingbird/internal/hummingbird/core/infrastructure/mysql"
)

// Assuming config and lc are already initialized
client, err := mysql.NewClient(config, lc)
if err != nil {
	// handle error
}

The hummingbird-core service is the primary entrypoint for the hummingbird core system. It initializes the service using the core.Main function, passing in a context, a cancellation function, and a Gin engine instance. The service operates on the /api/v1 base path and requires authentication via an x-token header.

// The service is typically run as a compiled binary.
// It uses the Gin framework in ReleaseMode.
// Authentication is required via the 'x-token' header.