{"id":28406740,"url":"https://github.com/eclipse-ditto/ditto-clients-golang","last_synced_at":"2025-06-29T09:32:43.573Z","repository":{"id":41836900,"uuid":"279258209","full_name":"eclipse-ditto/ditto-clients-golang","owner":"eclipse-ditto","description":"Eclipse Ditto™: Digital Twin framework - Client SDK for Golang","archived":false,"fork":false,"pushed_at":"2023-05-04T17:52:46.000Z","size":119,"stargazers_count":8,"open_issues_count":2,"forks_count":9,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-06-02T07:37:03.295Z","etag":null,"topics":["client-sdk","eclipse-ditto","golang","golang-library"],"latest_commit_sha":null,"homepage":"https://eclipse.org/ditto/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-ditto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-13T09:31:48.000Z","updated_at":"2025-05-13T16:38:59.000Z","dependencies_parsed_at":"2022-08-11T19:01:13.730Z","dependency_job_id":null,"html_url":"https://github.com/eclipse-ditto/ditto-clients-golang","commit_stats":null,"previous_names":["eclipse/ditto-clients-golang"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eclipse-ditto/ditto-clients-golang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ditto%2Fditto-clients-golang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ditto%2Fditto-clients-golang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ditto%2Fditto-clients-golang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ditto%2Fditto-clients-golang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-ditto","download_url":"https://codeload.github.com/eclipse-ditto/ditto-clients-golang/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-ditto%2Fditto-clients-golang/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262569822,"owners_count":23330286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-sdk","eclipse-ditto","golang","golang-library"],"created_at":"2025-06-01T22:36:45.156Z","updated_at":"2025-06-29T09:32:43.564Z","avatar_url":"https://github.com/eclipse-ditto.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Eclipse Ditto Client SDK for Golang\n\n[![Join the chat at https://gitter.im/eclipse/ditto](https://badges.gitter.im/eclipse/ditto.svg)](https://gitter.im/eclipse/ditto?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Go Reference](https://pkg.go.dev/badge/github.com/eclipse/ditto-clients-golang.svg)](https://pkg.go.dev/github.com/eclipse/ditto-clients-golang)\n[![Build Status](https://github.com/eclipse/ditto-clients-golang/workflows/Go/badge.svg)](https://github.com/eclipse/ditto-clients-golang/actions?query=workflow%3AGo)\n[![License](https://img.shields.io/badge/License-EPL%202.0-green.svg)](https://opensource.org/licenses/EPL-2.0)\n\nThis repository contains the Golang client SDK for [Eclipse Ditto](https://eclipse.org/ditto/).\n\nCurrently, [Eclipse Hono MQTT](https://www.eclipse.org/hono/docs/user-guide/mqtt-adapter/) is the only one supported transport.\n\nTable of Contents\n-----------------\n* [Installation](#Installation)\n* [Creating and connecting a client](#Creating-and-connecting-a-client)\n* [Working with features](#Working-with-features)\n    * [Create a new feature instance](#Create-new-feature-instance)\n    * [Modify a feature's property](#Modify-a-feature's-property)\n* [Subscribing and handling messages](#Subscribing-and-handling-messages)\n\n## Installation\n\n```\ngo get github.com/eclipse/ditto-clients-golang\n```\n\n## Creating and connecting a client\n\nEach client instance requires a ditto.Configuration object.\n\n```go\nconfig := ditto.NewConfiguration().\n    WithKeepAlive(30 * time.Second). // default keep alive is 30 seconds\n    // WithCredentials(\u0026ditto.Credentials{Username: \"John\", Password: \"qwerty\"}). if such are available or required\n    WithBroker(\"mqtt-host:1883\").\n    WithConnectHandler(connectHandler)\n\nfunc connectHandler(client ditto.Client) {\n    // add logic to be executed when the client is connected\n}\n```\n\nWith this configuration a client instance could be created.\n\n```go\nclient = ditto.NewClient(config)\n```\n**_NOTE:_** In some cases an external Paho instance could be provided for the communication. If this is the case, there is a ditto.NewClientMQTT() create function available.\n\nAfter you have configured and created your client instance, it's ready to be connected.\n```go\nif err := client.Connect(); err != nil {\n    panic(fmt.Errorf(\"cannot connect to broker: %v\", err))\n}\ndefer disconnect(client)\n```\n\n\n## Working with features\n\n### Create a new feature instance\n\nDefine the feature to be created.\n\n```go\nmyFeature := \u0026model.Feature{}\nmyFeature.\n    WithDefinitionFrom(\"my.model.namespace:FeatureModel:1.0.0\"). // you can provide a semantic definition of your feature\n    WithProperty(\"myProperty\", \"myValue\")\n```\n\nCreate your Ditto command. Modify acts as an upsert - it either updates or creates features.\n\n```go\ncommand := things.\n    NewCommand(model.NewNamespacedIDFrom(\"my.namespace:thing.id\")). // specify which thing you will send the command to\n    Twin().\n    Feature(\"MyFeature\").\n    Modify(myFeature) // the payload for the modification - i.e. the feature's JSON representation\n```\n\nSend the Ditto command.\n\n```go\nenvelope := command.Envelope(protocol.WithResponseRequired(false))\nif err := client.Send(envelope); err != nil {\n    fmt.Printf(\"could not send Ditto message: %v\\n\", err)\n}\n```\n\n### Modify a feature's property\n\nModify overrides the current feature's property.\n\n```go\ncommand = things.\n    NewCommand(model.NewNamespacedIDFrom(\"my.namespace:thing.id\")). // specify which thing you will send the command to\n    Twin().\n    FeatureProperty(\"MyFeature\", \"myProperty\").\n    Modify(\"myNewValue\") // the payload for the modification - i.e. the new property's value JSON representation\n```\n\n## Subscribing and handling messages\n\nSubscribe for incoming Ditto messages.\n\n```go\nfunc connectHandler(client ditto.Client) {\n    // it's a good practise to subscribe after the client is connected\n    client.Subscribe(messagesHandler)\n}\n```\n**_NOTE:_** You can add multiple handlers for Ditto messages processing.\n\nIt's a good practice to clear all subscriptions on client disconnect.\n```go\nfunc disconnect(client ditto.Client) {\n    // add any resources clearing logic\n    client.Unsubscribe()\n    client.Disconnect()\n}\n```\n**_NOTE:_** If no message handler is provided then all would be removed.\n\nHandle and reply to Ditto messages.\n\n```go\nfunc messagesHandler(requestID string, msg *protocol.Envelope) {\n    if msg.Topic.Namespace == \"my.namespace\" \u0026\u0026 msg.Topic.EntityID == \"thing.id\" \u0026\u0026\n            msg.Path == \"/features/MyFeature/inbox/messages/myCommand\" {\n        // respond to the message by using the outbox\n        response := things.NewMessage(model.NewNamespacedID(msg.Topic.Namespace, msg.Topic.EntityID)).\n            Feature(\"MyFeature\").Outbox(\"myCommand\").WithPayload(\"responsePayload\")\n        responseMsg := response.Envelope(protocol.WithCorrelationID(msg.Headers.CorrelationID()), protocol.WithResponseRequired(false))\n        responseMsg.Status = 200\n        if replyErr := client.Reply(requestID, responseMsg); replyErr != nil {\n            fmt.Printf(\"failed to send response to request Id %s: %v\\n\", requestID, replyErr)\n        }\n    }\n}\n```\n\n## Logging\n\nA custom logger could be implemented based on ditto.Logger interface. For example:\n\n```go\ntype logger struct {\n\tprefix string\n}\n\nfunc (l logger) Println(v ...interface{}) {\n    fmt.Println(l.prefix, fmt.Sprint(v...))\n}\n\nfunc (l logger) Printf(format string, v ...interface{}) {\n    fmt.Printf(fmt.Sprint(l.prefix, \" \", format), v...)\n}\n```\n\nThen the Ditto library could be configured to use the logger by assigning the logging endpoints - ERROR, WARN, INFO and DEBUG.\n\n```go\nfunc init() {\n    ditto.ERROR = logger{prefix: \"ERROR  \"}\n    ditto.WARN  = logger{prefix: \"WARN   \"}\n    ditto.INFO  = logger{prefix: \"INFO   \"}\n    ditto.DEBUG = logger{prefix: \"DEBUG  \"}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-ditto%2Fditto-clients-golang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-ditto%2Fditto-clients-golang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-ditto%2Fditto-clients-golang/lists"}