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.

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

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

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)
}

// 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
}

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
    }
}

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.

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

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.

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

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).