Crownstone Class Reference

Crownstone encapsulates all functionality, stack, services, and configuration. More...

#include <cs_Crownstone.h>

Inheritance diagram for Crownstone:

Collaboration diagram for Crownstone:

Public Types
enum	ServiceEvent {   CREATE_DEVICE_INFO_SERVICE , CREATE_SETUP_SERVICE , CREATE_CROWNSTONE_SERVICE , REMOVE_DEVICE_INFO_SERVICE ,   REMOVE_SETUP_SERVICE , REMOVE_CROWNSTONE_SERVICE }

Public Member Functions
	Crownstone (boards_config_t &board)
	Allocate Crownstone class and internal references. More...
void	init (uint16_t step)
	Initialize the crownstone: More...
void	startUp ()
	startup the crownstone: More...
void	run ()
	run main More...
void	handleEvent (event_t &event)
	handle (crownstone) events More...
Public Member Functions inherited from EventListener
	EventListener ()
virtual	~EventListener ()
	unregisters the listener. More...
virtual void	handleEvent (event_t &event)=0
	Handle events. More...
void	listen ()
	Registers this with the EventDispatcher. More...
Public Member Functions inherited from Component
template<class T >
T *	getComponent (Component *requester=nullptr)
	Returns a component of type T* from _parent->children(), If not found try again with ancestors: _parent-> ... ->_parent->children(). More...
virtual cs_ret_code_t	init ()
	Components can implement this if they need to get references to sibling or if they need to do specific initialization. More...
void	parentAllChildren ()
	utility that loops over all elements of getChildren() and setParent on the non-nullptr ones. More...
virtual	~Component ()=default

Static Public Member Functions
static void	updateHeapStats ()
	Update the heap statistics. More...
static void	updateMinStackEnd ()
	Update the minimal stack end location. More...
static void	printLoadStats ()
	Print load stats: RAM usage, app scheduler usage, etc. More...
static void	staticTick (Crownstone *ptr)
	tick function called by app timer More...

Protected Member Functions
std::vector< Component * >	getChildren () override
	Components with children can override this method to return them. More...
Protected Member Functions inherited from Component
virtual std::vector< Component * >	getChildren ()
	Components with children can override this method to return them. More...
cs_ret_code_t	initChildren ()
void	setParent (Component *p)
	Children that are instantiated later can also be added individually. More...

Private Member Functions
void	init0 ()
	The distinct init phases. More...
void	init1 ()
void	initDrivers0 ()
	initialize drivers (stack, timer, storage, pwm, etc), loads settings from storage. More...
void	initDrivers1 ()
	The distinct driver init phases. More...
void	configure ()
	configure the crownstone. More...
void	configureAdvertisement ()
	Sets default parameters of the Bluetooth connection. More...
void	setName ()
	The default name. More...
void	createService (const ServiceEvent event)
	Create a particular service. More...
void	createSetupServices ()
	Create services available in setup mode. More...
void	createCrownstoneServices ()
	Create services available in normal operation mode. More...
void	startOperationMode (const OperationMode &mode)
	Start operation for Crownstone. More...
void	switchMode (const OperationMode &mode)
	Switch from one operation mode to another. More...
void	tick ()
	tick function for crownstone to update/execute periodically More...
void	scheduleNextTick ()
	schedule next execution of tick function More...
void	increaseResetCounter ()
	Increase reset counter. More...
	TYPIFY (EVT_TICK) _tickCount=0

Private Attributes
boards_config_t	_boardsConfig
Stack *	_stack
BleCentral *	_bleCentral
CrownstoneCentral *	_crownstoneCentral
Advertiser *	_advertiser
Timer *	_timer
Storage *	_storage
State *	_state
TemperatureGuard *	_temperatureGuard = nullptr
PowerSampling *	_powerSampler = nullptr
DeviceInformationService *	_deviceInformationService = nullptr
CrownstoneService *	_crownstoneService = nullptr
SetupService *	_setupService = nullptr
ServiceData *	_serviceData = nullptr
CommandHandler *	_commandHandler = nullptr
Scanner *	_scanner = nullptr
FactoryReset *	_factoryReset = nullptr
CommandAdvHandler *	_commandAdvHandler = nullptr
MultiSwitchHandler *	_multiSwitchHandler = nullptr
SystemTime	_systemTime
SwitchAggregator	_switchAggregator
TrackedDevices	_trackedDevices
MeshTopology	_meshTopology
AssetFiltering	_assetFiltering
BehaviourStore	_behaviourStore
PresenceHandler	_presenceHandler
app_timer_t	_mainTimerData
app_timer_id_t	_mainTimerId
OperationMode	_operationMode
OperationMode	_oldOperationMode = OperationMode::OPERATION_MODE_UNINITIALIZED
uint32_t	_gpregret [2] = {0}
	Store gpregret as it was on boot. More...
uint32_t	_resetReason = 0
	Store reset reason as it was on boot. More...
bool	_setStateValuesAfterStorageRecover = false
	If storage was recovered by erasing all pages, we want to set some state variables different than after a factory reset. More...
bool	_clearedGpRegRetCount = false

Static Private Attributes
static cs_ram_stats_t	_ramStats

Friends
class	TestAccess< Crownstone >

Detailed Description

Crownstone encapsulates all functionality, stack, services, and configuration.

Member Enumeration Documentation

ServiceEvent

enum Crownstone::ServiceEvent

Enumerator
CREATE_DEVICE_INFO_SERVICE
CREATE_SETUP_SERVICE
CREATE_CROWNSTONE_SERVICE
REMOVE_DEVICE_INFO_SERVICE
REMOVE_SETUP_SERVICE
REMOVE_CROWNSTONE_SERVICE

Constructor & Destructor Documentation

Crownstone()

Crownstone::Crownstone

(

boards_config_t &

board

)

Allocate Crownstone class and internal references.

Create buffers, timers, storage, state, etc. We are running on an embedded device. Only allocate something in a constructor. For dynamic information use the stack. Do not allocate/deallocate anything during runtime. It is too risky. It might not be freed and memory might overflow. This type of hardware should run months without interruption.

There is a function IS_CROWNSTONE. What this actually is contrasted with are other BLE type devices, in particular the Guidestone. The latter devices do not have the ability to switch, dim, or measure power consumption.

The order with which items are created.

• buffers
• event distpatcher
• BLE stack
• timer
• persistent storage
• state
• command handler
• factory reset
• scanner
• tracker
• mesh
• switch
• temperature guard
• power sampling

The initialization is done in separate function.

Member Function Documentation

configure()

void Crownstone::configure ( )

private

configure the crownstone.

this will call the other configureXXX functions in turn

1. configure ble stack
2. set ble name
3. configure advertisement Configure the Bluetooth stack. This also increments the reset counter.

The order within this function is important. For example setName() sets the BLE device name and configureAdvertisements() defines advertisement parameters on appearance. These have to be called after the storage has been initialized.

configureAdvertisement()

void Crownstone::configureAdvertisement ( )

private

Sets default parameters of the Bluetooth connection.

Data is transmitted with TX_POWER dBm.

On transmission of data within a connection (higher interval -> lower power consumption, slow communication)

• minimum connection interval (in steps of 1.25 ms, 16*1.25 = 20 ms)
• maximum connection interval (in steps of 1.25 ms, 32*1.25 = 40 ms) The supervision timeout multiplier is 400 The slave latency is 10 On advertising:
• advertising interval (in steps of 0.625 ms, 1600*0.625 = 1 sec) (can be between 0x0020 and 0x4000)
• advertising timeout (disabled, can be between 0x0001 and 0x3FFF, and is in steps of seconds)

There is no whitelist defined, nor peer addresses.

Process: [31.05.16] we used to stop / start scanning after a disconnect, now starting advertising is enough [23.06.16] restart the mesh on disconnect, otherwise we have ~10s delay until the device starts advertising. [29.06.16] restart the mesh disabled, this was limited to pca10000, it does crash dobeacon v0.7 Populate advertisement (including service data) with information. The persistence mode is obtained from storage (the _operationMode var is not used).

createCrownstoneServices()

void Crownstone::createCrownstoneServices ( )

private

Create services available in normal operation mode.

createService()

void Crownstone::createService ( const ServiceEvent  event )

private

Create a particular service.

Depending on the mode we can choose to create a set of services that we would need. After creation of a service it cannot be deleted. This is a restriction of the Nordic Softdevice. If you need a new set of services, you will need to change the mode of operation (in a persisted field). Then you can restart the device and use the mode to enable another set of services.

createSetupServices()

void Crownstone::createSetupServices ( )

private

Create services available in setup mode.

getChildren()

std::vector< Component * > Crownstone::getChildren ( )

overrideprotectedvirtual

Components with children can override this method to return them.

This is used by getComponent<> to search for available components.

Reimplemented from Component.

handleEvent()

void Crownstone::handleEvent ( event_t &  event )

virtual

handle (crownstone) events

Handle events that can come from other parts of the Crownstone firmware and even originate from outside of the firmware via the BLE interface (an application, or the mesh).

Implements EventListener.

increaseResetCounter()

void Crownstone::increaseResetCounter ( )

private

Increase reset counter.

This will be stored in FLASH so it persists over reboots. Increase the reset counter. This can be used for debugging purposes. The reset counter is written to FLASH and persists over reboots.

init()

void Crownstone::init

(

uint16_t

step

)

Initialize the crownstone:

1. start UART
2. configure (drivers, stack, advertisement)
3. check operation mode 3a. for setup mode, create setup services 3b. for normal operation mode, create crownstone services and prepare Crownstone for operation
4. initialize services

Since some classes initialize asynchronous, this function is called multiple times to continue the process. When the class is initialized, the init done event will continue the initialization of other classes. Initialize Crownstone firmware. First drivers are initialized (log modules, storage modules, ADC conversion, timers). Then everything is configured independent of the mode (everything that is common to whatever mode the Crownstone runs on). A callback to the local staticTick function for a timer is set up. Then the mode of operation is switched and the BLE services are initialized.

init0()

void Crownstone::init0 ( )

private

The distinct init phases.

init1()

void Crownstone::init1 ( )

private

initDrivers0()

void Crownstone::initDrivers0 ( )

private

initialize drivers (stack, timer, storage, pwm, etc), loads settings from storage.

This must be called after the SoftDevice has started. The order in which things should be initialized is as follows:

1. Stack. Starts up the softdevice. It controls a lot of devices, so need to set it early.
2. Timer. Also initializes the app scheduler.
3. Storage. Definitely after the stack has been initialized.
4. State. Storage should be initialized here.

initDrivers1()

void Crownstone::initDrivers1 ( )

private

The distinct driver init phases.

• State
• UartHandler
• CommandHandler
• FactoryReset handler
• ConnectionEncryption
• KeysAndAccess
• SwitchAggregator
• TemperatureGuard
• PowerSampler
• TWI
• GPIO

printLoadStats()

static void Crownstone::printLoadStats ( )

static

Print load stats: RAM usage, app scheduler usage, etc.

run()

void Crownstone::run

(

)

run main

1. execute app scheduler
2. wait for ble events An infinite loop in which the application ceases control to the SoftDevice at regular times. It runs the scheduler, waits for events, and handles them. Also the printed statements in the log module are flushed.

scheduleNextTick()

void Crownstone::scheduleNextTick ( )

private

schedule next execution of tick function

setName()

void Crownstone::setName ( )

private

The default name.

This can later be altered by the user if the corresponding service and characteristic is enabled. It is loaded from memory or from the default and written to the Stack.

startOperationMode()

void Crownstone::startOperationMode ( const OperationMode &  mode )

private

Start operation for Crownstone.

This currently only enables parts in Normal operation mode. This includes:

• prepare mesh
• prepare scanner
• prepare tracker
• ... Start the different modules depending on the operational mode. For example, in normal mode we use a scanner and the mesh. In setup mode we use the serial module (but only RX).

startUp()

void Crownstone::startUp

(

)

startup the crownstone:

1. start advertising
2. start processing (mesh, scanner, tracker, tempGuard, etc) After allocation of all modules, after initialization of each module, and after configuration of each module, we are ready to "start". This means:

• advertise
• turn on/off switch at boot (depending on default)
• watch temperature excess
• power sampling
• schedule tasks

staticTick()

static void Crownstone::staticTick ( Crownstone *  ptr )

inlinestatic

tick function called by app timer

switchMode()

void Crownstone::switchMode ( const OperationMode &  mode )

private

Switch from one operation mode to another.

Depending on the operation mode we have a different set of services / characteristics enabled. Subsequently, also different entities are started (for example a scanner, or the BLE mesh).

tick()

void Crownstone::tick ( )

private

tick function for crownstone to update/execute periodically

Operations that are not sensitive with respect to time and only need to be called at regular intervals. TODO: describe function calls and why they are required.

TYPIFY()

Crownstone::TYPIFY ( EVT_TICK  )

privatepure virtual

updateHeapStats()

static void Crownstone::updateHeapStats ( )

static

Update the heap statistics.

updateMinStackEnd()

static void Crownstone::updateMinStackEnd ( )

static

Update the minimal stack end location.

Should be called regularly from high level interrupt.

Friends And Related Function Documentation

TestAccess< Crownstone >

friend class TestAccess< Crownstone >

friend

Member Data Documentation

_advertiser

Advertiser* Crownstone::_advertiser

private

_assetFiltering

AssetFiltering Crownstone::_assetFiltering

private

_behaviourStore

BehaviourStore Crownstone::_behaviourStore

private

_bleCentral

BleCentral* Crownstone::_bleCentral

private

_boardsConfig

boards_config_t Crownstone::_boardsConfig

private

_clearedGpRegRetCount

bool Crownstone::_clearedGpRegRetCount = false

private

_commandAdvHandler

CommandAdvHandler* Crownstone::_commandAdvHandler = nullptr

private

_commandHandler

CommandHandler* Crownstone::_commandHandler = nullptr

private

_crownstoneCentral

CrownstoneCentral* Crownstone::_crownstoneCentral

private

_crownstoneService

CrownstoneService* Crownstone::_crownstoneService = nullptr

private

_deviceInformationService

DeviceInformationService* Crownstone::_deviceInformationService = nullptr

private

_factoryReset

FactoryReset* Crownstone::_factoryReset = nullptr

private

_gpregret

uint32_t Crownstone::_gpregret[2] = {0}

private

Store gpregret as it was on boot.

_mainTimerData

app_timer_t Crownstone::_mainTimerData

private

_mainTimerId

app_timer_id_t Crownstone::_mainTimerId

private

_meshTopology

MeshTopology Crownstone::_meshTopology

private

_multiSwitchHandler

MultiSwitchHandler* Crownstone::_multiSwitchHandler = nullptr

private

_oldOperationMode

OperationMode Crownstone::_oldOperationMode = OperationMode::OPERATION_MODE_UNINITIALIZED

private

_operationMode

OperationMode Crownstone::_operationMode

private

_powerSampler

PowerSampling* Crownstone::_powerSampler = nullptr

private

_presenceHandler

PresenceHandler Crownstone::_presenceHandler

private

_ramStats

cs_ram_stats_t Crownstone::_ramStats

staticprivate

_resetReason

uint32_t Crownstone::_resetReason = 0

private

Store reset reason as it was on boot.

_scanner

Scanner* Crownstone::_scanner = nullptr

private

_serviceData

ServiceData* Crownstone::_serviceData = nullptr

private

_setStateValuesAfterStorageRecover

bool Crownstone::_setStateValuesAfterStorageRecover = false

private

If storage was recovered by erasing all pages, we want to set some state variables different than after a factory reset.

_setupService

SetupService* Crownstone::_setupService = nullptr

private

_stack

Stack* Crownstone::_stack

private

_state

State* Crownstone::_state

private

_storage

Storage* Crownstone::_storage

private

_switchAggregator

SwitchAggregator Crownstone::_switchAggregator

private

_systemTime

SystemTime Crownstone::_systemTime

private

_temperatureGuard

TemperatureGuard* Crownstone::_temperatureGuard = nullptr

private

_timer

Timer* Crownstone::_timer

private

_trackedDevices

TrackedDevices Crownstone::_trackedDevices

private

---

The documentation for this class was generated from the following file:

• source/include/cs_Crownstone.h