Omlox Hub Go Client Library

An Omlox Hub™ compatible Go client library and CLI tool.

Omlox is an open standard for precise real-time indoor localization systems. It specifies open interfaces for an interoperable localization system that enable industry to use a single infrastructure with different applications from different providers.

[!WARNING]
This library is currently being developed. Please try it out and give us feedback! Please do not use it in production or use at your own risk.

Contents

1. Installation
2. Examples
   • Getting Started
   • Websockets
     • Subscription
   • Error Handling
3. Status
   • Schemas
   • Methods
4. Specification
5. Community, discussion, contribution, and support
   • Code of conduct
6. Development
7. Disclaimer

Installation

go get -u github.com/wavecomtech/omlox-client-go

[!NOTE]
For the CLI installation, follow the documentation at ./docs/omlox-cli.md.

Examples

Getting Started

Here is a simple example of using the library to query the trackables in the hub.

package main

import (
    "context"
	"log"
	"time"

	"github.com/wavecomtech/omlox-client-go"
)

func main() {
    client, err := omlox.New("https://localhost:7081/v2")
    if err != nil {
        log.Fatal(err)
    }

    trackables, err := client.Trackables.List(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    log.Println("trackables retrieved:", trackables)
}

Websockets

Subscription

// Dials a Omlox Hub websocket interface, subscribes to
// the location_updates topic and listens to new
// location messages.

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

client, err := omlox.Connect(ctx, "localhost:7081/v2")
if err != nil {
    log.Fatal(err)
}
defer client.Close()

sub, err := client.Subscribe(ctx, omlox.TopicLocationUpdates)
if err != nil {
    log.Fatal(err)
}

for location := range omlox.ReceiveAs[omlox.Location](sub) {
    _ = location // handle location update
}

Error Handling

Errors are returned when Omlox Hub responds with an HTTP status code outside of the 200 to 399 range. If a request fails due to a network error, a different error message will be returned.

In go>=1.13 you can use the new errors.As method:

trackables, err := client.Trackables.List(context.Background())
if err != nil {
    var e *omlox.Error
    if errors.As(err, &e) && e.Code == http.StatusNotFound {
        // special handling for 404 errors
    }
}

For older go versions, you can also do type assertions:

trackables, err := client.Trackables.List(context.Background())
if err != nil {
    if e, ok := err.(*omlox.Error); ok && e.Code == http.StatusNotFound {
        // special handling for 404 errors
    }
}

Status

This library is coded from scratch to match the specification of Omlox Hub API. We plan to auto-generate most of it, but the OpenAPI spec is currently invalid due to some technical decisions in the spec. For the meantime, this library will continue to be coded from scratch.

An older iteration of this library is currently being used internally in Wavecom Technologies. We plan to migrate to the open source version earlier next year. The CLI is currently used by the RTLS team as a support tool for our internal Omlox Hub instance.

Following is the current checklist of the implemented schemas and API methods.

Schemas

[!WARNING]
The provided schemas are prone to change. Optional fields with default values have been the most challenging thing to translate well in to Go. We are trying different options and see which feels better.

Methods

Specification

The Hub specification can be found at: https://www.profibus.com/download/omlox-hub-specification-api-and-behavior.

Community, discussion, contribution, and support

Contributions are made to this repo via Issues and Pull Requests (PRs). If any part of the project has a bug or documentation mistakes, please let us know by opening an issue. The project is early in its development, so bugs and mistakes may appear.

To discuss API and feature suggestions, implementation insights and other things related to the implementation of the client, you can use Github's Discussions tab.

Before creating an issue, please check that an issue reporting the same problem does not already exist. Please try to create issues that are accurate and easy to understand. Maintainers might ask for further information to resolve the issue.

Code of conduct

By participating and contributing to this project, you agree to uphold our Code of Conduct.

Development

[!NOTE]
For an optimal developer experience, it is recommended to install Nix and direnv.

sh <(curl -L https://nixos.org/nix/install) --daemon

brew install direnv

curl -sfL https://direnv.net/install.sh | bash

eval "\$(direnv hook bash)"

Otherwise, you can install the required dependencies with Go itself.

Be sure to use Go >= to the one defined in go.mod and have $GOPATH/bin in your $PATH, so you can run installed go binaries. You can see how to do that at setup-your-shell-to-run-go-installed-binaries.

Install development dependencies:

go install github.com/mailru/easyjson/...@latest
go install github.com/hashicorp/copywrite@latest

You should be good to go! If you have any trouble getting started, reach out to us by email (see the MAINTAINERS file).

Disclaimer

[!NOTE]
The code provided by this library is not certified by Omlox or the Profibus & Profinet International. Solutions using this library should go through the certification process defined by the Omlox™ consortium to be an "omlox certified solution".