scheduling

package
v3.31.0 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2024 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package scheduling implements a packet scheduling that detects and avoids conflicts and enforces regional restrictions like duty-cycle and dwell time.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// QueueDelay indicates the time the gateway needs to recharge the concentrator between items in the queue.
	// This is a conservative value as implemented in the Semtech UDP Packet Forwarder reference implementation,
	// see https://github.com/Lora-net/packet_forwarder/blob/v4.0.1/lora_pkt_fwd/src/jitqueue.c#L39
	QueueDelay = 30 * time.Millisecond

	// ScheduleTimeShort is a short time to send a downlink message to the gateway before it has to be transmitted.
	// This time is comprised of a lower network latency and QueueDelay. This delay is used to block scheduling when the
	// schedule time to the estimated concentrator time is less than this value, see ScheduleAt.
	ScheduleTimeShort = 100*time.Millisecond + QueueDelay

	// ScheduleTimeLong is a long time to send a downlink message to the gateway before it has to be transmitted.
	// This time is comprised of a higher network latency and QueueDelay. This delay is used for pseudo-immediate
	// scheduling, see ScheduleAnytime.
	ScheduleTimeLong = 500*time.Millisecond + QueueDelay
)
View Source 
var DutyCycleWindow = 1 * time.Hour

DutyCycleWindow is the window in which duty-cycle is enforced. A lower value results in balancing capacity in time, while a higher value allows for bursts.

View Source 
var SystemTimeSource = &systemTimeSource{}

SystemTimeSource is a TimeSource that uses the local system time.

Functions

This section is empty.

Types

type Clock 

type Clock interface {
	// IsSynced returns whether the clock is synchronized.
	IsSynced() bool
	// SyncTime returns the server time of the last sync.
	// This method returns false if the clock is not synchronized.
	SyncTime() (time.Time, bool)
	// FromServerTime returns an indication of the concentrator time at the given server time.
	FromServerTime(time.Time) (ConcentratorTime, bool)
	// ToServerTime returns an indication of the server time at the given concentrator time.
	ToServerTime(ConcentratorTime) time.Time
	// FromGatewayTime returns an indication of the concentrator time at the given gateway time if available.
	FromGatewayTime(time.Time) (ConcentratorTime, bool)
	// FromTimestampTime returns the concentrator time for the given timestamp.
	FromTimestampTime(timestamp uint32) ConcentratorTime
}

Clock represents an absolute time source.

type ConcentratorTime 

type ConcentratorTime int64

ConcentratorTime is the time relative to the concentrator start time (nanoseconds).

type DutyCycleCeilings 

type DutyCycleCeilings map[ttnpb.TxSchedulePriority]float32

DutyCycleCeilings contains the upper limits per schedule priority. The limit is a fraction of the duty-cycle. 

var DefaultDutyCycleCeilings DutyCycleCeilings = map[ttnpb.TxSchedulePriority]float32{
	ttnpb.TxSchedulePriority_LOWEST:       0.40,
	ttnpb.TxSchedulePriority_LOW:          0.50,
	ttnpb.TxSchedulePriority_BELOW_NORMAL: 0.60,
	ttnpb.TxSchedulePriority_NORMAL:       0.70,
	ttnpb.TxSchedulePriority_ABOVE_NORMAL: 0.80,
	ttnpb.TxSchedulePriority_HIGH:         0.90,
	ttnpb.TxSchedulePriority_HIGHEST:      1.00,
}

DefaultDutyCycleCeilings contains the default duty-cycle ceilings per schedule priority.

type DutyCycleStyle added in v3.22.1 

type DutyCycleStyle int

DutyCycleStyle represents the of duty cycle algorithm to be used by a sub band. 

const (
	// DefaultDutyCycleStyle is the default duty cycle style.
	DefaultDutyCycleStyle = DutyCycleStyleSimpleWindow

	// DutyCycleStyleSimpleWindow uses a rolling window in order to compute the usage of a sub band.
	DutyCycleStyleSimpleWindow DutyCycleStyle = iota
	// DutyCycleStyleBlockingWindow uses a rolling window in order to compute the usage of a sub band.
	// The sub band is also blocked for the inverse duration of the non prioritized duty cycle.
	DutyCycleStyleBlockingWindow
)

type Emission 

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

Emission contains the scheduled time and duration of an emission.

func NewEmission 

func NewEmission(starts ConcentratorTime, duration time.Duration) Emission

NewEmission returns a new Emission with the given values.

func (Emission) AfterWithOffAir 

func (em Emission) AfterWithOffAir(other Emission, toa frequencyplans.TimeOffAir) time.Duration

AfterWithOffAir returns the time between the end of the given other emission to the start of this emission, considering time-off-air.

func (Emission) BeforeWithOffAir 

func (em Emission) BeforeWithOffAir(other Emission, toa frequencyplans.TimeOffAir) time.Duration

BeforeWithOffAir returns the time between the end of this emission to the start of the given other emission, considering time-off-air.

func (Emission) Duration 

func (em Emission) Duration() time.Duration

Duration returns the duration of the emission.

func (Emission) Ends 

func (em Emission) Ends() ConcentratorTime

Ends returns the time when the emission ends.

func (Emission) EndsWithOffAir 

func (em Emission) EndsWithOffAir(toa frequencyplans.TimeOffAir) ConcentratorTime

EndsWithOffAir returns the time when the emission ends plus the time-off-air.

func (Emission) OffAir 

func (em Emission) OffAir(toa frequencyplans.TimeOffAir) time.Duration

OffAir returns the time-off-air of the emission.

func (Emission) OverlapsWithOffAir 

func (em Emission) OverlapsWithOffAir(other Emission, toa frequencyplans.TimeOffAir) bool

OverlapsWithOffAir returns whether the given emission overlaps with this emission, considering time-off-air.

func (Emission) Starts 

func (em Emission) Starts() ConcentratorTime

Starts returns the time when the emission starts.

func (Emission) Within 

func (em Emission) Within(from, to ConcentratorTime) time.Duration

Within returns the duration of the emission that happens within the given window.

type Emissions 

type Emissions []Emission

Emissions is an list of emissions.

func (Emissions) GreaterThan added in v3.10.5 

func (ems Emissions) GreaterThan(to ConcentratorTime) Emissions

GreaterThan returns a new list of emissions that have not ended relative to the provided time.

func (Emissions) Insert 

func (ems Emissions) Insert(em Emission) Emissions

Insert inserts the given emission to the emissions by preserving order.

type Options added in v3.9.0 

type Options struct {
	PayloadSize int
	*ttnpb.TxSettings
	RTTs        RTTs
	Priority    ttnpb.TxSchedulePriority
	UplinkToken *ttnpb.UplinkToken
}

Options define options for scheduling downlink.

type RTTs 

type RTTs interface {
	Stats(percentile int, ref time.Time) (min, max, median, np time.Duration, count int)
}

RTTs provides round-trip times.

type RolloverClock 

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

RolloverClock is a Clock that takes roll-over of a uint32 microsecond concentrator time into account.

func (*RolloverClock) FromGatewayTime 

func (c *RolloverClock) FromGatewayTime(gateway time.Time) (ConcentratorTime, bool)

FromGatewayTime implements Clock.

func (*RolloverClock) FromServerTime 

func (c *RolloverClock) FromServerTime(server time.Time) (ConcentratorTime, bool)

FromServerTime implements Clock.

func (*RolloverClock) FromTimestampTime 

func (c *RolloverClock) FromTimestampTime(timestamp uint32) ConcentratorTime

FromTimestampTime implements Clock.

func (*RolloverClock) IsSynced 

func (c *RolloverClock) IsSynced() bool

IsSynced implements Clock.

func (*RolloverClock) Sync 

func (c *RolloverClock) Sync(timestamp uint32, server time.Time) ConcentratorTime

Sync synchronizes the clock with the given concentrator timestamp and the server time.

func (*RolloverClock) SyncTime added in v3.9.0 

func (c *RolloverClock) SyncTime() (time.Time, bool)

SyncTime implements Clock.

func (*RolloverClock) SyncWithGatewayAbsolute 

func (c *RolloverClock) SyncWithGatewayAbsolute(timestamp uint32, server, gateway time.Time) ConcentratorTime

SyncWithGatewayAbsolute synchronizes the clock with the given concentrator timestamp, the server time and the absolute gateway time that corresponds to the given timestamp.

func (*RolloverClock) SyncWithGatewayConcentrator 

func (c *RolloverClock) SyncWithGatewayConcentrator(timestamp uint32, server time.Time, gateway *time.Time, concentrator ConcentratorTime) ConcentratorTime

SyncWithGatewayConcentrator synchronizes the clock with the given concentrator timestamp, the server time and the relative gateway time that corresponds to the given timestamp.

func (*RolloverClock) ToServerTime 

func (c *RolloverClock) ToServerTime(t ConcentratorTime) time.Time

ToServerTime implements Clock.

type Scheduler 

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

Scheduler is a packet scheduler that takes time conflicts and sub-band restrictions into account.

func NewScheduler 

func NewScheduler(
	ctx context.Context,
	fps []*frequencyplans.FrequencyPlan,
	enforceDutyCycle bool,
	dutyCycleStyle DutyCycleStyle,
	scheduleAnytimeDelay *time.Duration,
	timeSource TimeSource,
) (*Scheduler, error)

NewScheduler instantiates a new Scheduler for the given frequency plan. If no time source is specified, the system time is used.

func (*Scheduler) IsGatewayTimeSynced 

func (s *Scheduler) IsGatewayTimeSynced() bool

IsGatewayTimeSynced reports whether scheduler clock is synchronized with gateway time.

func (*Scheduler) Now 

func (s *Scheduler) Now() (ConcentratorTime, bool)

Now returns an indication of the current concentrator time. This method returns false if the clock is not synced with the server.

func (*Scheduler) ScheduleAnytime 

func (s *Scheduler) ScheduleAnytime(ctx context.Context, opts Options) (res Emission, now ConcentratorTime, err error)

ScheduleAnytime attempts to schedule the given Tx settings with the given priority from the time in the settings. If there are round-trip times available, the maximum value will be used instead of ScheduleTimeShort. This method returns the emission.

The scheduler does not support immediate scheduling, i.e. sending a message to the gateway that should be transmitted immediately. The reason for this is that this scheduler cannot determine conflicts or enforce duty-cycle when the emission time is unknown. Therefore, when the time is set to Immediate, the estimated current concentrator time plus ScheduleDelayLong will be used.

func (*Scheduler) ScheduleAt 

func (s *Scheduler) ScheduleAt(ctx context.Context, opts Options) (res Emission, now ConcentratorTime, err error)

ScheduleAt attempts to schedule the given Tx settings with the given priority. If there are round-trip times available, the nth percentile (n = scheduleLateRTTPercentile) value will be used instead of ScheduleTimeShort.

func (*Scheduler) SubBandCount 

func (s *Scheduler) SubBandCount() int

SubBandCount returns the number of sub bands in the scheduler.

func (*Scheduler) SubBandStats added in v3.9.0 

func (s *Scheduler) SubBandStats() []*ttnpb.GatewayConnectionStats_SubBand

SubBandStats returns a map with the usage stats of each sub band.

func (*Scheduler) Sync 

func (s *Scheduler) Sync(v uint32, server time.Time) ConcentratorTime

Sync synchronizes the clock with the given concentrator time v and the server time.

func (*Scheduler) SyncWithGatewayAbsolute 

func (s *Scheduler) SyncWithGatewayAbsolute(timestamp uint32, server, gateway time.Time) ConcentratorTime

SyncWithGatewayAbsolute synchronizes the clock with the given concentrator timestamp, the server time and the absolute gateway time that corresponds to the given timestamp.

func (*Scheduler) SyncWithGatewayConcentrator 

func (s *Scheduler) SyncWithGatewayConcentrator(timestamp uint32, server time.Time, gateway *time.Time, concentrator ConcentratorTime) ConcentratorTime

SyncWithGatewayConcentrator synchronizes the clock with the given concentrator timestamp, the server time and the relative gateway time that corresponds to the given timestamp.

func (*Scheduler) TimeFromServerTime added in v3.16.0 

func (s *Scheduler) TimeFromServerTime(t time.Time) (ConcentratorTime, bool)

TimeFromServerTime returns an indication of the provided timestamp in concentrator time. This method returns false if the clock is not synced with the server.

func (*Scheduler) TimeFromTimestampTime 

func (s *Scheduler) TimeFromTimestampTime(t uint32) (ConcentratorTime, bool)

TimeFromTimestampTime returns the concentrator time by the given timestamp. This method returns false if the clock is not synced with the server.

type SubBand 

type SubBand struct {
	SubBandParameters
	// contains filtered or unexported fields
}

SubBand tracks the utilization and controls the duty-cycle of a sub-band.

func NewSubBand 

func NewSubBand(
	params SubBandParameters, clock Clock, ceilings DutyCycleCeilings, style DutyCycleStyle,
) *SubBand

NewSubBand returns a new SubBand considering the given duty-cycle, clock and optionally duty-cycle ceilings.

func (*SubBand) DutyCycleUtilization 

func (sb *SubBand) DutyCycleUtilization() float32

DutyCycleUtilization returns the utilization as a fraction of the available duty-cycle.

func (*SubBand) HasOverlap 

func (sb *SubBand) HasOverlap(subBand *SubBand) bool

HasOverlap checks if the two sub bands have an overlap.

func (*SubBand) IsIdentical 

func (sb *SubBand) IsIdentical(subBand *SubBand) bool

IsIdentical checks if the two sub bands are identical.

func (*SubBand) Schedule 

func (sb *SubBand) Schedule(em Emission, p ttnpb.TxSchedulePriority) error

Schedule schedules the given emission with the priority. If there is no time available due to duty-cycle limitations, an error with code ResourceExhausted is returned.

func (*SubBand) ScheduleAnytime 

func (sb *SubBand) ScheduleAnytime(d time.Duration, next func() ConcentratorTime, p ttnpb.TxSchedulePriority) (Emission, error)

ScheduleAnytime schedules the given duration at a time when there is availability by accounting for duty-cycle. The given next callback should return the next option that does not conflict with other scheduled downlinks. If there is no duty-cycle limitation, this method returns the first option.

type SubBandParameters 

type SubBandParameters struct {
	MinFrequency,
	MaxFrequency uint64
	DutyCycle float32
}

SubBandParameters defines the sub-band frequency bounds and duty-cycle value.

func (SubBandParameters) Comprises 

func (sb SubBandParameters) Comprises(frequency uint64) bool

Comprises returns whether the given frequency falls in the sub-band.

type TimeSource 

type TimeSource interface {
	Now() time.Time
}

TimeSource is a source for getting a current time.

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.