gopi

README

Go Language Application Framework

This repository contains an application framework for the Go language, which will allow you to develop applications which utilize a number of features of your computer. It's targetted at the Raspberry Pi presently. The following features are intended to be supported:

• The GPIO, I2C and SPI interfaces
• Display and display surfaces, bitmaps and vector graphics
• GPU acceleration for 2D graphics
• Font loading and rendering in bitmap and vector forms
• Input devices like the mouse, keyboard and touchscreen
• Infrared transmission and receiving, for example for remote controls
• Network microservices, announcement and discovery

It would also be great to support the following features in the future:

• Image and video encoding/decoding, including utilizing hardware acceleration
• Connected cameras
• 3D graphics
• Audio devices
• User interface widgets and layout
• Building for Darwin (Macintosh) targets

Requirements

The tested requirements are currently:

• Any Raspberry Pi (v2, v3, Zero and Zero W have been tested)
• Raspbian GNU/Linux 9 (other distributions may work, but not tested)
• Go 1.12

In order to use the library, you'll need to have a working version of Go on your Raspberry Pi, which you can download. Then retrieve the library on your device, using:

go get github.com/djthorpe/gopi

The gopi repository is mostly just a set of interfaces and some utility packages. Other repositories provide implementation:

Repository	Link	Module
gopi-hw	http://github.com/djthorpe/gopi-hw/	Hardware implementations
gopi-graphics	http://github.com/djthorpe/gopi-graphics/	Graphics & Fonts
gopi-rpc	http://github.com/djthorpe/gopi-rpc/	Microservices & Discovery
gopi-input	http://github.com/djthorpe/gopi-input/	Input services (Keyboard, Mouse, Touchscreen)

Please see each repository for more example code and information on the modules provided.

Getting Started

In order to get started, build some of the examples in the "cmd" folder. They can be built with the makefile.

• make will run the tests and install the examples
• make install will build and install the examples without testing
• make clean will remove intermediate files

There are two examples in this repository you can examine in order so you can develop your own applications:

• helloworld demonstrates the most canonical code, taking in command-line arguments, outputting a message and waiting for user input to end the program;
• timers demonstrates the use of the timer module, either outputting a single message, or one on a repeating basis.

Fuller documentation of the examples and developing your own code against this framework is available in the documentation.

Modules

This repository contains two modules:

Module	Import	Type	Name
Logger	github.com/djthorpe/gopi/sys/logger	gopi.MODULE_TYPE_LOGGER	sys/logger
Timer	github.com/djthorpe/gopi/sys/timer	gopi.MODULE_TYPE_TIMER	sys/timer

Logger

The logger module provides very basic logging functionality. Here is the interface for any logging module:

type Logger interface {
  Driver

  // Output logging messages
  Fatal(format string, v ...interface{}) error
  Error(format string, v ...interface{}) error
  Warn(format string, v ...interface{})
  Info(format string, v ...interface{})
  Debug(format string, v ...interface{})
  Debug2(format string, v ...interface{})

  // Return IsDebug flag
  IsDebug() bool
}

A logger module is required for every application which uses this framework, so include the module in your main package:

package main

import (
  // Frameworks
  "github.com/djthorpe/gopi"

  // Modules
  _ "github.com/djthorpe/gopi/sys/logger"
)

The logger is then available as app.Logger within your application, and is also passed to every gopi module with the Open method. The standard logger includes some command-line flags in case you want to log to a file, rather than to stderr:

$ helloworld -help
Usage of helloworld:
  -debug
    	Set debugging mode
  -log.append
    	When writing log to file, append output to end of file
  -log.file string
    	File for logging (default: log to stderr)
  -verbose
    	Verbose logging

Logging occurs depending on the combination of the debug and verbose flags, according to the following rules:

Debug	Verbose	Levels logged
false	false	Fatal, Error and Warn
false	true	Fatal, Error, Warn and Info
true	false	Fatal, Error, Warn, Info and Debug
true	true	Fatal, Error, Warn, Info, Debug and Debug2

Timer

The timer module emits gopi.Event objects once, at regular intervals, or at intervals according to a backoff rule. The timer interface is as follows:

type Timer interface {
  Driver
  Publisher

  // Schedule a timeout (one shot)
  NewTimeout(duration time.Duration, userInfo interface{})

  // Schedule an interval, which can fire immediately
  NewInterval(duration time.Duration, userInfo interface{}, immediately bool)

  // Schedule a backoff timer with maximum backoff
  NewBackoff(duration time.Duration, max_duration time.Duration, userInfo interface{})
}

You can subscribe to emitted events which are as follows:

type TimerEvent interface {
  Event

  // Provide the timestamp for the event
  Timestamp() time.Time

  // The user info for the event
  UserInfo() interface{}

  // Cancel the timer which fired this event
  Cancel()
}

License

Copyright 2016-2018 David Thorpe All Rights Reserved

Redistribution and use in source and binary forms, with or without 
modification, are permitted with some conditions. 

This repository is released under the BSD License. Please see the file LICENSE for a copy of this license and for a list of the conditions for redistribution and use.

Documentation

Index

• func UnitRegister(unit UnitConfig)
• type App
• type Bus
• type Config
• type ConfigFunc
• type Error
  • func (this Error) Error() string
  • func (this Error) WithPrefix(prefix string) error
• type Event
• type EventHandler
• type EventNS
• type Flags
• type Logger
• type LoggerBase
  • func (this *LoggerBase) Debug(args ...interface{})
  • func (this *LoggerBase) Error(err error) error
  • func (this *LoggerBase) Init(writer io.Writer, name string, debug bool) error
  • func (this *LoggerBase) IsDebug() bool
  • func (this *LoggerBase) Name() string
• type MainCommandFunc
• type Timer
• type TimerId
• type Unit
  • func New(config Config, log Logger) (Unit, error)
• type UnitBase
  • func (this *UnitBase) Close() error
  • func (this *UnitBase) Init(log Logger) error
  • func (this *UnitBase) String() string
• type UnitConfig
  • func UnitsByName(unitName string) []UnitConfig
  • func UnitsByType(unitType UnitType) []UnitConfig
  • func (u UnitConfig) String() string
• type UnitType
  • func (v UnitType) String() string

Functions

func UnitRegister

func UnitRegister(unit UnitConfig)

Types

type App

type App interface {
	Run() int // Run application

	Flags() Flags // Return command-line flags
	Log() Logger  // Return logger unit
	Timer() Timer // Return timer unit
	Bus() Bus     // Return event bus unit

	Unit(string) Unit    // Return singular unit for name
	Units(string) []Unit // Return multiple units for name
}

type Bus

type Bus interface {
	Unit

	Emit(Event)                      // Emit an event on the bus
	NewHandler(string, EventHandler) // Register an event handler for an event name
}

Bus unit - handles events

type Config

type Config interface {
	Name() string             // Returns name of the unit
	New(Logger) (Unit, error) // Opens the driver from configuration, or returns error
}

Unit configuration interface

type ConfigFunc

type ConfigFunc func(App) error

type Error

type Error uint

const (
	ErrNone           Error = iota // No error condition
	ErrNotImplemented              // Method or feature not implemented
	ErrBadParameter                // Error with parameter passed to method
	ErrNotFound                    // Missing object
	ErrHelp                        // Help requested from command line
)

func (Error) Error

func (this Error) Error() string

func (Error) WithPrefix

func (this Error) WithPrefix(prefix string) error

type Event

type Event interface {
	Source() Unit       // Source of the event
	Name() string       // Name of the event
	NS() EventNS        // Namespace for the event
	Value() interface{} // Any value associated with the event
}

Event emitted on the event bus

type EventHandler

type EventHandler func(Event) // Handler for an emitted event

type EventNS

type EventNS uint // Event namespace

const (
	EVENT_NS_DEFAULT EventNS = iota // Default event namespace
)

type Flags

type Flags interface {
	Name() string        // Return name of flagset
	Args() []string      // Args returns the command line arguments
	HasFlag(string) bool // HasFlag returns true if a flag exists

	FlagBool(name string, value bool, usage string) *bool
	FlagString(name, value, usage string) *string
	FlagDuration(name string, value time.Duration, usage string) *time.Duration
	FlagInt(name string, value int, usage string) *int
	FlagUint(name string, value uint, usage string) *uint
	FlagFloat64(name string, value float64, usage string) *float64

	GetBool(string) bool
	GetString(string) string
	GetDuration(string) time.Duration
	GetInt(string) int
	GetUint(string) uint
	GetFloat64(string) float64
}

type Logger

type Logger interface {
	Unit

	Name() string              // Return unit name
	Error(error) error         // Output logging messages
	Debug(args ...interface{}) // Debug output
	IsDebug() bool             // Return IsDebug flag
}

Abstract logging interface

type LoggerBase

type LoggerBase struct {
	UnitBase
	// contains filtered or unexported fields
}

LoggerBase is the struct for any logger

func (*LoggerBase) Debug

func (this *LoggerBase) Debug(args ...interface{})

func (*LoggerBase) Error

func (this *LoggerBase) Error(err error) error

func (*LoggerBase) Init

func (this *LoggerBase) Init(writer io.Writer, name string, debug bool) error

func (*LoggerBase) IsDebug

func (this *LoggerBase) IsDebug() bool

func (*LoggerBase) Name

func (this *LoggerBase) Name() string

type MainCommandFunc

type MainCommandFunc func(App, []string) error

type Timer

type Timer interface {
	Unit

	NewTicker(time.Duration) TimerId // Create periodic event at interval
	NewTimer(time.Duration) TimerId  // Create one-shot event after interval
	Cancel(TimerId) error            // Cancel events
}

Timer unit - sends out messages on the event bus

type TimerId

type TimerId uint // Unique ID for each timer created

type Unit

type Unit interface {
	Close() error   // Close closes the driver and frees the underlying resources
	String() string // String returns a string representation of the unit
}

Unit interface

func New

func New(config Config, log Logger) (Unit, error)

type UnitBase

type UnitBase struct {
	Log Logger
}

UnitBase is the struct for any unit

func (*UnitBase) Close

func (this *UnitBase) Close() error

func (*UnitBase) Init

func (this *UnitBase) Init(log Logger) error

func (*UnitBase) String

func (this *UnitBase) String() string

type UnitConfig

type UnitConfig struct {
	Name     string   // Unique name of the unit
	Type     UnitType // Unit type
	Requires []string // Unit dependencies
	Config   ConfigFunc
}

func UnitsByName

func UnitsByName(unitName string) []UnitConfig

func UnitsByType

func UnitsByType(unitType UnitType) []UnitConfig

func (UnitConfig) String

func (u UnitConfig) String() string

type UnitType

type UnitType uint

const (
	UNIT_NONE UnitType = iota
	UNIT_LOGGER
	UNIT_TIMER
	UNIT_BUS
	UNIT_MAX = UNIT_BUS
)

func (UnitType) String

func (v UnitType) String() string