rtc

package module
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Nov 28, 2020 License: MIT Imports: 9 Imported by: 1

README

rtc

Go module for using a hardware Real-Time Clock (RTC) device in Linux.

Installation

$ go get github.com/cleroux/rtc

Usage

rtc.NewTicker() and rtc.NewTimer() provide high-level interfaces inspired by Go's time.NewTicker() and time.NewTimer() with the obvious difference being that the rtc functions trigger directly from the RTC's hardware interrupts.

The following example creates a ticker that fires at 2 Hz.

t, err := rtc.NewTicker("/dev/rtc", 2)
if err != nil {
  panic(err)
}
defer t.Stop()

for {
  select {
  case tick := <-t.Chan:
    fmt.Printf("Tick.  Frame:%d Time:%v Delta:%v Missed:%d\n", tick.Frame, tick.Time, tick.Delta, tick.Missed)
  }
}

The following example sets an alarm for 5 seconds in the future and waits for the alarm to fire.

t, err := rtc.NewTimer("/dev/rtc", time.Now().Add(time.Second * 5))
if err != nil {
  panic(err)
}
defer t.Stop()

select {
case alarm := <-t.Chan:
  fmt.Printf("Alarm.  Time:%v\n", alarm.Time)
}

If more flexible programming of the RTC is needed, rtc.NewRTC() instantiates an object that exposes all RTC functionality. The RTC device file is kept open until Close() is called.

c, err := rtc.NewRTC("/dev/rtc")
if err != nil {
  return err
}
defer c.Close()

t, err := c.Time()

Lastly, for convenience, static utility functions are also provided. These functions are ideal when just a single function or operation is necessary because they open and close the RTC device. For example, if reading the RTC's time as in the following example:

t, err := rtc.Time("/dev/rtc")
if err != nil {
  panic(err)
}
fmt.Printf("Current time: %v\n", t)

References

[1] The Linux kernel user's and administrator's guide: Real Time Clock (RTC) Drivers for Linux
[2] rtc - Linux manual page

License

See the LICENSE file for license rights and limitations (MIT).

Documentation

Overview

The rtc package facilitates working with real-time clocks (RTCs). High level functions such as NewTicker and NewTimer encapsulate the details of working with the RTC while providing interfaces that are similar to Go's time.NewTicker and time.NewTimer respectively. If more flexible programming of the RTC is needed, the NewRTC function returns an rtc object that exposes all RTC functionality. When this object is instantiated, the RTC device file is kept open until the Close function is called. For convenience, static utility functions are also provided to open and close the RTC when only one function is needed. For example, reading the clock once is possible simply by calling rtc.Time(). Note that when working with the RTC, the highest resolution for time values is one second as defined in unix.RTCTime. https://www.kernel.org/doc/html/latest/admin-guide/rtc.html https://blog.cloudflare.com/its-go-time-on-linux/ https://man7.org/linux/man-pages/man4/rtc.4.html https://code.woboq.org/linux/linux/drivers/char/rtc.c.html

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Alarm 

func Alarm(dev string) (t time.Time, err error)

Alarm returns the alarm time for the specified real-time clock device.

Example 
if t, err := Alarm("/dev/rtc"); err == nil {
	fmt.Printf("Current alarm time: %v\n", t)
}

Output:

func CancelWakeAlarm 

func CancelWakeAlarm(dev string) (err error)

CancelWakeAlarm cancels the wake alarm for the specified real-time clock device.

func Clocks 

func Clocks() (devices []string, err error)

Clocks returns a list of real-time clocks in the system.

Example 
if cs, err := Clocks(); err == nil {
	for _, c := range cs {
		fmt.Printf("Clock found: %s\n", c)
	}
}

Output:

func Epoch 

func Epoch(dev string) (epoch uint, err error)

Epoch reads the epoch from the specified real-time clock device.

Example 
if e, err := Epoch("/dev/rtc"); err == nil {
	fmt.Printf("Current epoch: %d\n", e)
}

Output:

func Frequency 

func Frequency(dev string) (frequency uint, err error)

Frequency returns the frequency of the specified real-time clock device.

Example 
if f, err := Frequency("/dev/rtc"); err == nil {
	fmt.Printf("Frequency: %d\n", f)
}

Output:

func NewRTC 

func NewRTC(dev string) (*rtc, error)

NewRTC opens a real-time clock device.

func SetAlarm 

func SetAlarm(dev string, t time.Time) (err error)

SetAlarm sets the alarm time for the specified real-time clock device.

Example 
if err := SetAlarm("/dev/rtc", time.Now().Add(time.Minute)); err != nil {
	panic(err)
}

Output:

func SetAlarmInterrupt 

func SetAlarmInterrupt(dev string, enable bool) (err error)

SetAlarmInterrupt enables or disables the alarm interrupt for the specified real-time clock device.

Example 
if err := SetAlarmInterrupt("/dev/rtc", true); err != nil {
	panic(err)
}

Output:

func SetEpoch 

func SetEpoch(dev string, epoch uint) (err error)

Epoch sets the epoch on the specified real-time clock device.

Example 
if err := SetEpoch("/dev/rtc", 99); err != nil {
	panic(err)
}

Output:

func SetFrequency 

func SetFrequency(dev string, frequency uint) (err error)

SetFrequency sets the periodic interrupt frequency of the specified real-time clock device.

Example 
if err := SetFrequency("/dev/rtc", 64); err != nil {
	panic(err)
}

Output:

func SetPeriodicInterrupt 

func SetPeriodicInterrupt(dev string, enable bool) (err error)

SetPeriodicInterrupt enables or disables periodic interrupts for the specified real-time clock device.

func SetTime 

func SetTime(dev string, t time.Time) (err error)

SetTime sets the time for the specified real-time clock device.

Example 
if err := SetTime("/dev/rtc", time.Now()); err != nil {
	panic(err)
}

Output:

func SetUpdateInterrupt 

func SetUpdateInterrupt(dev string, enable bool) (err error)

SetUpdateInterrupt enables or disables the update interrupt for the specified real-time clock device.

func SetWakeAlarm 

func SetWakeAlarm(dev string, t time.Time) (err error)

SetWakeAlarm sets the wake alarm time for the specified real-time clock device.

func Time 

func Time(dev string) (t time.Time, err error)

Time reads the time from the specified real-time clock device.

Example 
if t, err := Time("/dev/rtc"); err == nil {
	fmt.Printf("Current time: %v\n", t)
}

Output:

func WakeAlarm 

func WakeAlarm(dev string) (enabled bool, pending bool, t time.Time, err error)

WakeAlarm returns the current state of the wake alarm for the specified real-time clock device.

Types

type Ticker added in v0.1.1 

type Ticker struct {
	Chan <-chan tick
	// contains filtered or unexported fields
}

func NewTicker 

func NewTicker(dev string, frequency uint) (*Ticker, error)
Example 
ticker, err := NewTicker("/dev/rtc", 2)
if err != nil {
	panic(err)
}
defer ticker.Stop()

for {
	select {
	case tick := <-ticker.Chan:
		fmt.Printf("Tick.  Frame:%d Time:%v Delta:%v Over:%d\n", tick.Frame, tick.Time, tick.Delta, tick.Missed)
	}
}

Output:

func (*Ticker) Stop added in v0.1.1 

func (t *Ticker) Stop()

type Timer added in v0.1.1 

type Timer struct {
	Chan <-chan alarm
	// contains filtered or unexported fields
}

func NewTimer 

func NewTimer(dev string, d time.Duration) (*Timer, error)

TODO: Timer resolution limited to 1 second TODO: What to do if d < 1 second? TODO: Consider mimicking the time.After() patterns

Example 
t, err := NewTimer("/dev/rtc", time.Minute)
if err != nil {
	panic(err)
}
defer t.Stop()

select {
case alarm := <-t.Chan:
	fmt.Printf("Alarm.  Time:%v\n", alarm.Time)
}

Output:

func NewTimerAt 

func NewTimerAt(dev string, t time.Time) (*Timer, error)

NewTimerAt creates a timer that will trigger an alarm at the given time.

func (*Timer) Stop added in v0.1.1 

func (t *Timer) Stop()

Source Files

View all Source files

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.