omlox

package module
v0.0.0-...-00ba440 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 25, 2024 License: MIT Imports: 25 Imported by: 0

README

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
  3. Status
  4. Specification
  5. Community, discussion, contribution, and support
  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.

Schema Implemented
Collision
CollisionEvent
Error ✅
Fence
FenceEvent
LineString
LocatingRule
Location
LocationProvider ✅
Point ✅
Polygon ✅
Proximity
Trackable ✅
TrackableMotion
WebsocketError ✅
WebsocketMessage API abstracted
WebSocketSubscriptionResponse API abstracted
WebsocketSubscriptionRequest API abstracted
Zone
Methods
Method Endpoint Implemented
GET /zones/summary
GET /zones
POST /zones
DELETE /zones
GET /zones/:zoneID
PUT /zones/:zoneID
DELETE /zones/:zoneID
PUT /zones/:zoneID/transform
GET /zones/:zoneID/createfence
Method Endpoint Implemented
GET /trackables/summary ✅
GET /trackables ✅
POST /trackables ✅
DELETE /trackables ✅
GET /trackables/:trackableID ✅
DELETE /trackables/:trackableID ✅
PUT /trackables/:trackableID
GET /trackables/:trackableID/fences
GET /trackables/:trackableID/location ✅
GET /trackables/:trackableID/locations
GET /trackables/:trackableID/motion
GET /trackables/:trackableID/providers
GET /trackables/:trackableID/sensors
GET /trackables/motions
Method Endpoint Implemented
GET /providers/summary ✅
GET /providers ✅
POST /providers ✅
DELETE /providers ✅
GET /providers/:providerID ✅
PUT /providers/:providerID
DELETE /providers/:providerID ✅
PUT /providers/:providerID/location
GET /providers/:providerID/location
DELETE /providers/:providerID/location
GET /providers/:providerID/fences
PUT /providers/:providerID/sensors
GET /providers/:providerID/sensors
GET /providers/locations
PUT /providers/locations
DELETE /providers/locations
PUT /providers/:providerID/proximity
PUT /providers/proximities
Method Endpoint Implemented
GET /fences/summary
GET /fences
POST /fences
DELETE /fences
GET /fences/:fenceID
PUT /fences/:fenceID
DELETE /fences/:fenceID
GET /fences/:fenceID/providers
GET /fences/:fenceID/locations

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.

Installing Nix and direnv

Note: These are instructions that SHOULD work in most cases. Consult the links above for the official instructions for your OS.

Install Nix:

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

Consult the installation instructions to install direnv using your package manager.

On MacOS:

brew install direnv

Install from binary builds:

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

The last step is to configure your shell to use direnv. For example for bash, add the following lines at the end of your ~/.bashrc:

eval "\$(direnv hook bash)"

Then restart the shell.

For other shells, see https://direnv.net/docs/hook.html.

MacOS specific instructions

Nix may stop working after a MacOS upgrade. If it does, follow these instructions.

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

Documentation

Overview

An OmloxHub™ compatible Go client library.

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.

See more at https://omlox.com/.

Index

Examples

Constants

View Source 
const (
	// Inf is the constant value representing infite.
	Inf = -1
)

Variables

View Source 
var (
	ErrBadWrapperObject = errors.New("invalid wrapper object")
	ErrTimeout          = errors.New("timeout")
)

Errors

View Source 
var ErrCodeMap = map[ErrCode]string{
	ErrCodeUnknown:        "event type is unknown",
	ErrCodeUnknownTopic:   "unknown topic name",
	ErrCodeSubscription:   "subscription failed",
	ErrCodeUnsubscription: "unsubscribe failed",
	ErrCodeNotAuthorized:  "not authorized",
	ErrCodeInvalid:        "invalid payload data",
}

Map between error codes and their text representation. It is public to facilitate adding custom error codes for client extensions.

View Source 
var (
	SubscriptionTimeout = 3 * time.Second
)

Functions

func ReceiveAs 

func ReceiveAs[T any](sub *Subcription) <-chan *T

Types

type Client 

type Client struct {
	Trackables TrackablesAPI
	Providers  ProvidersAPI
	// contains filtered or unexported fields
}

Client manages communication with Omlox™ Hub client.

func Connect 

func Connect(ctx context.Context, addr string, options ...ClientOption) (*Client, error)

Connect will attempt to connect to the Omlox™ Hub websockets interface.

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

Output:

func New 

func New(addr string, options ...ClientOption) (*Client, error)

New returns a new client decorated with the given configuration options

Example 
c, err := omlox.New("localhost:8081/v2")
if err != nil {
	log.Fatal(err)
}

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

_ = trackables // use trackables

Output:

func (*Client) Close 

func (c *Client) Close() error

Close releases any resources held by the client, such as connections, memory and goroutines.

func (*Client) Connect 

func (c *Client) Connect(ctx context.Context) error

Connect dials the Omlox™ Hub websockets interface.

func (*Client) Publish 

func (c *Client) Publish(ctx context.Context, topic Topic, payload ...json.RawMessage) error

Publish a message to the Omlox Hub.

func (*Client) Subscribe 

func (c *Client) Subscribe(ctx context.Context, topic Topic, params ...Parameter) (*Subcription, error)

Subscribe to a topic in Omlox Hub.

type ClientConfiguration 

type ClientConfiguration struct {
	// HTTPClient is the HTTP client to use for all API requests.
	HTTPClient *http.Client

	// RequestTimeout, given a non-negative value, will apply the timeout to
	// each request function unless an earlier deadline is passed to the
	// request function through context.Context.
	//
	// Default: 60s
	RequestTimeout time.Duration

	// RateLimiter controls how frequently requests are allowed to happen.
	// If this pointer is nil, then there will be no limit set. Note that an
	// empty struct rate.Limiter is equivalent to blocking all requests.
	//
	// Default: nil
	RateLimiter *rate.Limiter

	// UserAgent sets a name for the http client User-Agent header.
	UserAgent string
}

/ ClientConfiguration is used to configure the creation of the client.

func DefaultConfiguration 

func DefaultConfiguration() ClientConfiguration

GetDefaultOptions returns default configuration options for the client.

type ClientOption 

type ClientOption func(*ClientConfiguration) error

ClientOption is a configuration option to initialize a client.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets the HTTP client to use for all API requests.

func WithRateLimiter 

func WithRateLimiter(limiter *rate.Limiter) ClientOption

WithRateLimiter configures how frequently requests are allowed to happen. If this pointer is nil, then there will be no limit set. Note that an empty struct rate.Limiter is equivalent to blocking all requests.

Default: nil

func WithRequestTimeout 

func WithRequestTimeout(timeout time.Duration) ClientOption

WithRequestTimeout, given a non-negative value, will apply the timeout to each request function unless an earlier deadline is passed to the request function through context.Context.

Default: 60s

type Duration 

type Duration struct {
	// contains filtered or unexported fields
}

Duration is an Omlox type that provides infinite semantics for a time duration. Must be a positive number or -1 in case of an infinite duration. All negative durations are considered infinite.

func NewDuration 

func NewDuration(v int) Duration

Create an infinite type of millisecond duration type.

func (*Duration) Duration 

func (v *Duration) Duration() time.Duration

Duration returns a time.Duration. If its a infinite duration, it returns a maximum duration possible.

func (Duration) Equal 

func (v Duration) Equal(y Duration) bool

func (Duration) Inf 

func (v Duration) Inf() bool

Inf return true on infinite value.

func (Duration) IsDefined 

func (v Duration) IsDefined() bool

IsDefined returns whether the value is defined. A function is required so that it can be used as easyjson.Optional interface.

func (Duration) MarshalEasyJSON 

func (v Duration) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON does JSON marshaling using easyjson interface.

func (Duration) MarshalJSON 

func (v Duration) MarshalJSON() ([]byte, error)

MarshalJSON implements a standard json marshaler interface. If the value is infinite, it will be ignored.

func (Duration) String 

func (v Duration) String() string

String implements a stringer interface using fmt.Sprint for the value.

func (*Duration) UnmarshalEasyJSON 

func (v *Duration) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON does JSON unmarshaling using easyjson interface.

func (*Duration) UnmarshalJSON 

func (v *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON implements a standard json unmarshaler interface.

type ElevationRefType 

type ElevationRefType int

An elevation reference hint for the position's z component. Must be either 'floor' or 'wgs84'. 

const (
	ElevationRefTypeFloor ElevationRefType = iota
	ElevationRefTypeWgs84
)

Defines values for ElevationRefType.

func (*ElevationRefType) FromString 

func (e *ElevationRefType) FromString(name string) error

FromString assigs itself from type name.

func (ElevationRefType) MarshalJSON 

func (e ElevationRefType) MarshalJSON() ([]byte, error)

MarshalJSON encodes type in to JSON.

func (ElevationRefType) String 

func (e ElevationRefType) String() string

String return a text representation.

func (*ElevationRefType) UnmarshalJSON 

func (e *ElevationRefType) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes type from JSON.

type ErrCode 

type ErrCode int

ErrCode is an error code used by applications to discern the type of the websocket error. 

const (
	// Event type is unknown.
	ErrCodeUnknown ErrCode = 10000

	// Unknown topic name.
	ErrCodeUnknownTopic ErrCode = 10001

	// Subscription failed.
	ErrCodeSubscription ErrCode = 10002

	// Unsubscribe failed.
	ErrCodeUnsubscription ErrCode = 10003

	// Not authorized.
	ErrCodeNotAuthorized ErrCode = 10004

	// Invalid payload data.
	ErrCodeInvalid ErrCode = 10005
)

func (ErrCode) String 

func (e ErrCode) String() string

String return a text representation.

type Error 

type Error struct {
	// A text representation of the error type (required).
	Type string `json:"type"`

	// HTTP status code (required).
	Code int `json:"code"`

	// A human readable error message which may give a hint to what went wrong (optional).
	Message string `json:"message"`
}

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

func (Error) Error 

func (err Error) Error() string

func (Error) LogValue 

func (err Error) LogValue() slog.Value

LogValue implements [slog.LogValuer] to convert itself into a Value for logging.

type Event 

type Event string

event abstracts the possible events types in websocket messages. 

const (
	EventMsg          Event = "message"
	EventSubscribe    Event = "subscribe"
	EventSubscribed   Event = "subscribed"
	EventUnsubscribe  Event = "unsubscribe"
	EventUnsubscribed Event = "unsubscribed"
	EventError        Event = "error"
)

func (*Event) UnmarshalJSON 

func (e *Event) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes type from JSON.

type LocatingRule 

type LocatingRule struct {
	// The conditions of the LocatingRule.
	// Supported properties are: accuracy, provider_id, type, source, floor, speed, timestamp_diff.
	Expression string

	// The priority of the LocatingRule.
	// The higher the value the higher the priority of the rule.
	Priority int
}

The rule syntax is a simple Boolean expression consisting of AND connected expressions. Each Boolean expression is assigned a positive number as priority.

type Location 

type Location struct {
	// A GeoJson Point geometry. Describes a point (e.g. a position) in 2 or 3 dimensions. Important: A Point object MUST be interpreted
	// according to a coordinate reference system (crs), e.g. the crs field in the Location object. In practice this means a Position
	// object for example contains relative x,y,z data from a UWB system given in the coordinate system of a local zone and a
	// transformation needs to be applied to convert the position to a geographic coordinate. But the Position might also contain a
	// geographic coordinate (longitude, latitude) for example from a GPS system (where no coordinate transformation is needed), or
	// position data in projection of a UTM zone (where again transformation is required). The ordering of components is x,y,z or
	// longitude,latitude,elevation respectively as according to the GeoJson specification.
	Position Point `json:"position"`

	// Represents the unique identifier of the RTLS system (zone_id or foreign_id) which generated this location object, or the id of
	// a self-localizing device (e.g. a UWB tag / provider_id in GPS mode).
	Source string `json:"source"`

	// The location provider type which triggered this location update.
	ProviderType LocationProviderType `json:"provider_type"`

	// The location provider unique identifier, e.g. the mac address of a UWB location provider.
	ProviderID string `json:"provider_id"`

	// The ids of trackables the provider is assigned to.
	Trackables []uuid.UUID `json:"trackables,omitempty"`

	// The timestamp when the location was calculated.
	// The timestamp MUST be an ISO 8601 timestamp using UTC timezone and it SHOULD have millisecond precision to allow for precise
	// speed and course calculations. If no timestamp is provided, the hub will use its local current time.
	TimestampGenerated *time.Time `json:"timestamp_generated,omitempty"`

	// The timestamp when the location was sent over the network.
	// The optional timestamp MUST be an ISO 8601 timestamp using UTC timezone and it SHOULD have millisecond precision.
	// Note: No delivery guarantee is made in case the data is lost in transit.
	TimestampSent *time.Time `json:"timestamp_sent,omitempty"`

	// A projection identifier defining the projection of the provided location coordinate. The crs MUST be either a valid EPSG identifier
	// (https://epsg.io) or 'local' if the locations provided as a relative coordinate of the floor plan. For best interoperability and
	// worldwide coverage WGS84 (EPSG:4326) SHOULD be the preferred projection (as used also by GPS).
	// If the crs field is not present, 'local' MUST be assumed as the default.
	Crs string `json:"crs,omitempty"`

	// Whether a client is currently associated to a network. This property SHOULD be set if available for WiFi based positioning.
	Associated bool `json:"associated,omitempty"`

	// The horizontal accuracy of the location update in meters.
	Accuracy *float64 `json:"accuracy,omitempty"`

	// A logical and non-localized representation for a building floor. Floor 0 represents the floor designated as 'ground'.
	// Negative numbers designate floors below the ground floor and positive to indicate floors above the ground floor.
	// When implemented the floor value MUST match described logical numbering scheme, which can be different from any numbering used
	// within a building. Values can be expressed as an integer value, or as a float as required for mezzanine floor levels.
	Floor float64 `json:"floor,omitempty"`

	// An accurate orientation reading from a 'true' heading direction. The 'true' magnetic as opposed to the normal magnetic heading.
	// Applications SHOULD prefer the true heading if available. An invalid or currently unavailable heading MUST be indicated by
	// a negative value.
	TrueHeading *float64 `json:"true_heading,omitempty"`

	// The magnetic heading direction, which deviates from the true heading by a few degrees and differs slightly depending on
	// the location on the globe.
	MagneticHeading *float64 `json:"magnetic_heading,omitempty"`

	// The maximum deviation in degrees between the reported heading and the true heading.
	HeadingAccuracy *float64 `json:"heading_accuracy,omitempty"`

	// An elevation reference hint for the position's z component. If present it MUST be either 'floor' or 'wgs84'. If set to 'floor'
	// the z component MUST be assumed to be relative to the floor level. If set to 'wgs84' the z component MUST be treated as WGS84
	// ellipsoidal height. For the majority of applications an accurate geographic height may not be available. Therefore elevation_ref
	// MUST be assumed 'floor' by default if this property is not present.
	ElevationRef *ElevationRefType `json:"elevation_ref,omitempty"`

	// The current speed in meters per second. If the value is null or the property is not set, the current speed MAY be approximated
	// by an omlox™ hub based on the timestamp_generated value of a previous location update.
	Speed *float64 `json:"speed,omitempty"`

	// The current course ("compass direction"), which is the direction measured clockwise as an angle from true north on a compass
	// (north is 0°, east is 90°, south is 180°, and west is 270°). If the value is null or the property not set the course will be
	// approximated by an omlox™ hub based on the previous location.
	Course *float64 `json:"course,omitempty"`

	// Any additional application or vendor specific properties. An application implementing this  object is not required to interpret
	// any of the custom properties, but it MUST preserve the properties if set.
	Properties json.RawMessage `json:"properties,omitempty"`
}

Location defines model for Location.

func (Location) MarshalEasyJSON 

func (v Location) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Location) MarshalJSON 

func (v Location) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Location) UnmarshalEasyJSON 

func (v *Location) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Location) UnmarshalJSON 

func (v *Location) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type LocationProvider 

type LocationProvider struct {
	// Must be a valid id for the specific location provider type (e.g. a MAC address of a UWB tag).
	// Wherever applicable, the format of a MAC address SHOULD be an upper case EUI-64 hex-string representation, built from unsigned values. The id MUST including leading zeros and MUST use colon as byte delimiter.
	// IDs which can not be mapped to EUI- 64 MAY deviate from this format.
	ID string `json:"id"`

	// Type of the location provider.
	// A virtual location provider can be used for assigning a unique id to a location provider
	// which does not have a unique identifier by itself.
	// For example, an iOS app will not get the MAC address of the Wi-Fi interface for WiFi positioning.
	// Instead, it will create a virtual location provider to identify the provider and the trackable (iOS device) for location updates.
	Type LocationProviderType `json:"type"`

	// An optional name for the location provider.
	Name string `json:"name,omitempty"`

	// Sensors data related to a provider.
	// The actual structure of the sensors data is application defined.
	Sensors interface{} `json:"sensors,omitempty"`

	// The timeout in milliseconds after which a location should expire
	// and trigger a fence exit event (if no more location updates are sent).
	// Must be a positive number or -1 in case of an infinite timeout.
	// If not set, or set to null, it will default to the trackable or fence setting.
	FenceTimeout Duration `json:"fence_timeout,omitempty"`

	// The minimum distance in meters to release from an ongoing collision or fence event.
	// Must be a positive number. If not set or null exit_tolerance will default to 0.
	ExitTolerance float64 `json:"exit_tolerance,omitempty"`

	// The timeout in milliseconds after which a collision outside of an obstacle but still within exit_tolerance distance
	// should release from a collision or fence event.
	// Must be a positive number or -1 in case of an infinite timeout.
	// If not set, or set to null, it will default to the fence or trackable setting.
	ToleranceTimeout Duration `json:"tolerance_timeout,omitempty"`

	// The delay in milliseconds in which an imminent exit event should wait for another location update.
	// This is relevant for fast rate position updates with quick moving objects.
	// For example, an RTLS provider may batch location updates into groups, resulting in distances being temporarily outdated
	// and premature events between quickly moving objects.
	// The provided number must be positive or -1 in case of an infinite exit_delay.
	// If not set, or set to null, it will default to the fence or trackable setting.
	ExitDelay Duration `json:"exit_delay,omitempty"`

	// Any additional application or vendor specific properties.
	// An application implementing this object is not required to interpret any of the custom properties,
	// but it MUST preserve the properties if set.
	Properties json.RawMessage `json:"properties,omitempty"`
}

LocationProvider defines model for LocationProvider.

func (LocationProvider) MarshalEasyJSON 

func (v LocationProvider) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (LocationProvider) MarshalJSON 

func (v LocationProvider) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*LocationProvider) UnmarshalEasyJSON 

func (v *LocationProvider) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*LocationProvider) UnmarshalJSON 

func (v *LocationProvider) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type LocationProviderType 

type LocationProviderType int

The location provider type which triggered this location update. 

const (
	LocationProviderTypeUnknown LocationProviderType = iota
	LocationProviderTypeUwb
	LocationProviderTypeGps
	LocationProviderTypeWifi
	LocationProviderTypeRfid
	LocationProviderTypeIbeacon
	LocationProviderTypeVirtual
)

Defines values for LocationProviderType.

func (*LocationProviderType) FromString 

func (t *LocationProviderType) FromString(name string) error

FromString assigs itself from type name.

func (LocationProviderType) MarshalJSON 

func (t LocationProviderType) MarshalJSON() ([]byte, error)

MarshalJSON encodes type in to JSON.

func (LocationProviderType) String 

func (t LocationProviderType) String() string

String return a text representation.

func (*LocationProviderType) UnmarshalJSON 

func (t *LocationProviderType) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes type from JSON.

type Parameter 

type Parameter func(Topic, Parameters) error

Parameter is an optional key-value pair used on subscriptions. If a parameter is unsupported for a certain reason, it must return an error.

type Parameters 

type Parameters map[string]string

Parameters represents the key-value pairs used in subscriptions.

func (Parameters) LogValue 

func (p Parameters) LogValue() slog.Value

type Point 

type Point struct {
	geojson.Point
}

func NewPoint 

func NewPoint(point geometry.Point) *Point

func NewPointZ 

func NewPointZ(point geometry.Point, z float64) *Point

func (Point) Equal 

func (p Point) Equal(u Point) bool

func (Point) MarshalJSON 

func (p Point) MarshalJSON() ([]byte, error)

func (*Point) UnmarshalJSON 

func (p *Point) UnmarshalJSON(data []byte) error

type Polygon 

type Polygon struct {
	geojson.Polygon
}

func NewPolygon 

func NewPolygon(poly *geometry.Poly) *Polygon

func (Polygon) Equal 

func (p Polygon) Equal(u Polygon) bool

func (Polygon) MarshalJSON 

func (p Polygon) MarshalJSON() ([]byte, error)

func (*Polygon) UnmarshalJSON 

func (p *Polygon) UnmarshalJSON(data []byte) error

type ProvidersAPI 

type ProvidersAPI struct {
	// contains filtered or unexported fields
}

ProvidersAPI is a simple wrapper around the client for location provider requests.

func (*ProvidersAPI) Create 

func (c *ProvidersAPI) Create(ctx context.Context, provider LocationProvider) (*LocationProvider, error)

Create creates a location provider.

func (*ProvidersAPI) Delete 

func (c *ProvidersAPI) Delete(ctx context.Context, id string) error

Delete deletes a location provider.

func (*ProvidersAPI) DeleteAll 

func (c *ProvidersAPI) DeleteAll(ctx context.Context) error

DeleteAll deletes all location providers.

func (*ProvidersAPI) Get 

func (c *ProvidersAPI) Get(ctx context.Context, id string) (*LocationProvider, error)

Get gets a location providers.

func (*ProvidersAPI) IDs 

func (c *ProvidersAPI) IDs(ctx context.Context) ([]string, error)

IDs lists all location providers IDs.

func (*ProvidersAPI) List 

func (c *ProvidersAPI) List(ctx context.Context) ([]LocationProvider, error)

List lists all location providers.

type Subcription 

type Subcription struct {
	// contains filtered or unexported fields
}

Subcription represents a topic subscription to the websocket Hub interface.

func (Subcription) ReceiveRaw 

func (s Subcription) ReceiveRaw() <-chan *WrapperObject

type Topic 

type Topic string

Omlox Hub supports a a few topics to which clients can subscribe and publish. 

const (
	// For real-time location updates, as well as sending location updates to the hub.
	// When receiving data for this topic the payload of the wrapper object contains omlox™ Location objects.
	TopicLocationUpdates Topic = "location_updates"

	// To retrieve location information as GeoJson feature collection.
	TopicLocationUpdatesGeoJSON Topic = "location_updates:geojson"

	// Checks trackable movements for collisions and sends collision events when trackables:
	// start to collide, continue to collide and end a collision.
	// When receiving data for this topic the payload of the wrapper object contains omlox™ CollisionEvent objects.
	TopicCollisionEvents Topic = "collision_events"

	// To inform subscribers about geofence entry and exit events.
	// When receiving data for this topic the payload of the wrapper object contains omlox™ FenceEvent objects.
	TopicFenceEvents Topic = "fence_events"

	// Similar to fence events, but instead of an omlox™ FenceEvent object GeoJson feature collections are returned as payload.
	TopicFenceEventsGeoJSON Topic = "fence_events:geojson"

	// To receive movements of omlox™ Trackables.
	// When receiving data for this topic, the payload of the wrapper object contains omlox™ TrackableMotion objects.
	TopicTrackableMotions Topic = "trackable_motions"
)

type Trackable 

type Trackable struct {
	// Must be a UUID. When creating a trackable, a unique id will be generated if it is not provided.
	ID uuid.UUID `json:"id"`

	// Either 'omlox' or 'virtual'. An omlox™ compatible trackable has knowledge of it's location providers
	// (e.g. embedded UWB, BLE, RFID hardware), and self-assigns it's location providers.
	// A virtual trackable can be used to assign location providers to a logical asset.
	Type TrackableType `json:"type"`

	// A describing name
	Name string `json:"name,omitempty"`

	// GeoJson Polygon geometry. Important: A Polygon object MUST be interpreted according to a coordinate reference system (crs).
	// The ordering of components is x,y,z or longitude,latitude,elevation respectively as according to the GeoJson specification.
	Geometry *Polygon `json:"geometry,omitempty"`

	// The extrusion to be applied to the geometry in meters.
	// Must be a positive number.
	Extrusion float64 `json:"extrusion,omitempty"`

	// The location provider ids (e.g. mac addresses) assigned to this trackable.
	// Note: An application may create virtual location providers and assign these to a trackable where desired.
	// This allows applications to identify trackables for location providers which themselve do not have a
	// unique identifier (e.g. certain GPS devices).
	LocationProviders []string `json:"location_providers,omitempty"`

	// The timeout in milliseconds after which a location should expire and optional
	// trigger a fence exit event (if no more location updates are sent).
	// Must be a positive number or -1 in case of an infinite timeout.
	// If not set, or set to null, it will default to the fence setting.
	FenceTimeout Duration `json:"fence_timeout,omitempty"`

	// The minimum distance in meters for a trackable to release from an ongoing collision.
	// For example, for a trackable that was previously colliding with another trackable by being inside a trackable's radius, the collision
	// event will not be released from the collision until its distance to the trackable's geometry is at least the given exit_tolerance.
	// Must be a positive number. If not set, or set to null, it will default to the fence setting.
	ExitTolerance float64 `json:"exit_tolerance,omitempty"`

	// The timeout in milliseconds after which collision outside of a trackable but still within exit_tolerance distance to another
	// obstacle should release from a collision.
	// Must be a positive number or -1 in case of an infinite timeout.
	// If not set, or set to null, it will default to the fence setting.
	ToleranceTimeout Duration `json:"tolerance_timeout,omitempty"`

	// The delay in milliseconds in which an imminent exit event should wait for another location update.
	// This is relevant for fast rate position updates with quickly moving objects.
	// For example, an RTLS provider may batch location updates into groups, resulting in distances being temporarily outdated and
	// premature events between quickly moving objects.
	// The provided number must be positive or -1 in case of an infinite exit_delay.
	// If not set, or set to null, it will default to the fence setting.
	ExitDelay Duration `json:"exit_delay,omitempty"`

	// A radius provided in meters, defining the approximate circumference of the trackable.
	// If a radius value is set, all position updates from any of the Location Providers will generate a circular geometry
	// for the trackable, where the position is the center and the circle will be generated with the given radius.
	Radius float64 `json:"radius,omitempty"`

	// Any additional application or vendor specific properties.
	// An application implementing this object is not required to interpret any of the custom properties,
	// but it MUST preserve the properties if set.
	Properties json.RawMessage `json:"properties,omitempty"`

	// When a location update is processed, the locating rules of a trackable are applied to all its associated locations,
	// to determine its most significant location:
	// If a Boolean expression evaluates to true, the priority for the expression is applied to the location.
	// If multiple expressions evaluate to true, the highest priority is applied.
	// The location with the highest priority is considered the most significant location of that trackable.
	// If multiple locations share the highest priority, the most recent of these locations is the most significant.
	LocatingRules []LocatingRule `json:"locating_rules,omitempty"`
}

Trackable defines model for Trackable.

func (Trackable) MarshalEasyJSON 

func (v Trackable) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Trackable) MarshalJSON 

func (v Trackable) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Trackable) UnmarshalEasyJSON 

func (v *Trackable) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Trackable) UnmarshalJSON 

func (v *Trackable) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type TrackableType 

type TrackableType int

Either 'omlox' or 'virtual'. An omlox™ compatible trackable has knowledge of it's location providers (e.g. embedded UWB, BLE, RFID hardware), and self-assigns it's location providers. A virtual trackable can be used to assign location providers to a logical asset. 

const (
	TrackableTypeOmlox TrackableType = iota
	TrackableTypeVirtual
)

Defines values for TrackableType.

func (*TrackableType) FromString 

func (t *TrackableType) FromString(name string) error

FromString assigs itself from type name.

func (TrackableType) MarshalJSON 

func (t TrackableType) MarshalJSON() ([]byte, error)

MarshalJSON encodes type in to JSON.

func (TrackableType) String 

func (t TrackableType) String() string

String return a text representation.

func (*TrackableType) UnmarshalJSON 

func (t *TrackableType) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes type from JSON.

type TrackablesAPI 

type TrackablesAPI struct {
	// contains filtered or unexported fields
}

TrackablesAPI is a simple wrapper around the client for trackables requests.

func (*TrackablesAPI) Create 

func (c *TrackablesAPI) Create(ctx context.Context, trackable Trackable) (*Trackable, error)

Create creates a trackable.

func (*TrackablesAPI) Delete 

func (c *TrackablesAPI) Delete(ctx context.Context, id uuid.UUID) error

Delete deletes a trackable.

func (*TrackablesAPI) DeleteAll 

func (c *TrackablesAPI) DeleteAll(ctx context.Context) error

DeleteAll deletes all trackables.

func (*TrackablesAPI) Get 

func (c *TrackablesAPI) Get(ctx context.Context, id uuid.UUID) (*Trackable, error)

Get gets a trackable.

func (*TrackablesAPI) GetLocation 

func (c *TrackablesAPI) GetLocation(ctx context.Context, id uuid.UUID) (*Location, error)

GetLocation gets the last most recent location for a trackable. It considers all recent location updates of the trackables location providers.

func (*TrackablesAPI) IDs 

func (c *TrackablesAPI) IDs(ctx context.Context) ([]uuid.UUID, error)

IDs lists all trackable IDs.

func (*TrackablesAPI) List 

func (c *TrackablesAPI) List(ctx context.Context) ([]Trackable, error)

List lists all trackables.

type WebsocketError 

type WebsocketError struct {
	Code        ErrCode `json:"code,omitempty"`
	Description string  `json:"description,omitempty"`
}

WebsocketError sent to the client on websocket server error.

func (WebsocketError) Error 

func (err WebsocketError) Error() string

func (WebsocketError) LogValue 

func (err WebsocketError) LogValue() slog.Value

func (WebsocketError) MarshalEasyJSON 

func (v WebsocketError) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (WebsocketError) MarshalJSON 

func (v WebsocketError) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*WebsocketError) UnmarshalEasyJSON 

func (v *WebsocketError) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*WebsocketError) UnmarshalJSON 

func (v *WebsocketError) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type WrapperObject 

type WrapperObject struct {
	// Event is always required for all data exchanged between client and server.
	Event Event `json:"event"`
	Topic Topic `json:"topic,omitempty"`

	// The concrete topic subscription which generated the data.
	SubscriptionID int `json:"subscription_id,omitempty"`

	// An array containing valid omlox™ data objects (or empty).
	Payload []json.RawMessage `json:"payload,omitempty"`

	// Optional object containing key-value pairs of parameters.
	// Parameters usually match their REST API counterparts.
	Params Parameters `json:"params,omitempty"`
}

WrapperObject is the wrapper object of websockets data exchanged between client and server.

func (WrapperObject) LogValue 

func (w WrapperObject) LogValue() slog.Value

LogValue implements slog.LogValuer.

func (WrapperObject) MarshalEasyJSON 

func (v WrapperObject) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (WrapperObject) MarshalJSON 

func (v WrapperObject) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*WrapperObject) UnmarshalEasyJSON 

func (v *WrapperObject) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*WrapperObject) UnmarshalJSON 

func (v *WrapperObject) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

Source Files

View all Source files

Directories

Path Synopsis
cmd
omlox-cli
internal
cli
cli/log
cli/output
cli/resource

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.