EnOcean Gateway class, for handling a gateway Module. More...

#include <eoGateway.h>

Inheritance diagram for eoGateway:

Collaboration diagram for eoGateway:

[legend]

Public Member Functions
void	LearnModeOn ()
	Activates Learn Mode.

void	LearnModeOff ()
	Deactivates Learn Mode.

uint32_t	GetSecWatchResult () const
	Returns the security Result of the eoIWatcher Interface.

	eoGateway ()

	eoGateway (eoDeviceManager *devManager)

	eoGateway (eoPacketStream *str)

	eoGateway (eoPacketStream str, eoDeviceManager devManager)

	eoGateway (eoPacketStream str, eoDeviceManager devManager, eoIFilter normFilter, eoIFilter lrnFilter)

uint16_t	Receive ()
	Handles received Telegrams. More...

virtual eoReturn	Send (const eoPacket &p)

virtual eoReturn	Send (const eoMessage &msg)

virtual eoReturn	Send (const eoReManMessage &reMsg, bool shallBeRepeated=false, uint8_t keyToUse=0)

virtual eoReturn	Send (const eoMaintenanceMessage &manMsg)

eoReturn	Open (const char *port)

void	Close ()

uint8_t	Serialize (eoArchive &arch)
	Serialization Function which will be called by the eoStorageManager. More...

Public Attributes
eoPacketStream *	stream
	Pointer to the eoPacketStream Handler.

eoTeachInModule *	TeachInModule
	Pointer to eoTeachInModule.

eoDeviceManager *	deviceManager
	Pointer to the device manager, handling your Devices.

eoIFilter *	filter

eoIFilter *	learnFilter

eoIWatcher *	secWatcher
	security Watcher to Use

bool	LearnMode
	When true, activates LearnMode until set to False.

uint8_t	errorCode
	contains the last Error Code from the receive function

eoDevice *	device
	Pointer to the device, to which the last received Telegram belongs. More...

eoPacket	packet
	received Packet data More...

eoPacket	responsePacket
	Response Packet after sending any sort of Packet/Message/Telegram with the Gateway.

eoTelegram	telegram
	received Telegram More...

eoTelegramERP2	telegramERP2
	received Telegram More...

eoMessage	message
	received Message More...

eoMaintenanceMessage	maintenanceMessage
	received Maintenance Message More...

eoReManMessage	reManMessage
	received Remote Management Message More...

eoSerialCommand	commands
	Common Commands.

bool	advancedMode
	ERP2 mode turned on.

eoSecurity	security
	Security handler for the gateway.

Detailed Description

EnOcean Gateway class, for handling a gateway Module.

The eoGateway class, allows you to easily handle Packages received from an EnOcean Gateway module(USB300,TCM310...). with simple calls you can learn in Devices, add filters, check if you received a Message and send packets.
The eoGateway has two different modes the learnMode and the normalMode. After creating the eoGateway the Gateway is in the normalMode, the following steps explain the functionality of the receive function.

Receive packet
Is Telegram?
Encrypted Telegram-> if Yes decrypt
Is the Telegram a part of a chained Message?
Telegram gets handled and can be accessed unless it gets filtered.
Telegram is Maintenance Telegram? The gateway atomically merges the telegrams and decrypts it if the maintenance key is known. The RECV_MAINTENANCE is set. If it is SEC_SYS_EX maintenance message, it is automatically copied to the remanMessage and RECV_REMAN is set.
1. Learn MODE!
  Uses the learnFilter (if it is set) to Filter telegrams. Always add the Device to device Manager(flag|=RECV_DEVICE_ADDED), when it is a Security Teach IN, store secure Information. The eoGateway::device is set accordingly.
  
  When an EEP Teach IN telegram is received, it is handled by the eoTeachInModule. If the telegram contains the func,type the right eoProfile will be created. As for rps no Teach IN telegram is specified you've to use eoTeachInModule::SetRPS function.
  
  If you receive a second Teach IN from a learned IN EEP device the RECV_SECTEACHIN will be set.
2. Normal Mode Uses the filter (if it is set) to Filter telegrams. If the device is in the deviceManager it is set to the Device, otherwise it returns a dummy device with the ID 0, which is not in the deviceManger.
If we get a EEP TeachIN telegram(4bs or 1bs) set the RECV_TEACHIN flag, so you're application can handle always teachINS
If the gateway has a profile saved for the received telegram, parse the data and set RECV_PROFILE

Note: deviceManger,stream and TeachInModule will be destroyed in the Destructor, if you need to keep them, set the Pointer to NULL before calling the Destructor!; To be sure that no telegram gets missed, ensure that eoGateway::Receive() is called at least once every 100ms.

Examples:: commands_example.cpp, Gateway_example.cpp, Gateway_SubtypeExample.cpp, GatewayFiltered_example.cpp, genericProfile_examples.cpp, HelloWorld.cpp, Security_example.cpp, sendTelegram_example.cpp, storage_example.cpp, tutorial1.cpp, tutorial2.cpp, tutorial3.cpp, tutorial4.cpp, tutorial5.cpp, tutorial6.cpp, vld_example.cpp, and WatcherMain.cpp.

Constructor & Destructor Documentation

◆ eoGateway() [1/5]

eoGateway::eoGateway ( )

Creates your EnOcean gateway class, with the hardware specific PacketStream Handler and a new DeviceManager

◆ eoGateway() [2/5]

eoGateway::eoGateway ( eoDeviceManager * devManager )

Creates your EnOcean gateway class, with the hardware specific PacketStream Handler.

Parameters

devManager - creates a Gateway with a specified eoDeviceManager.

◆ eoGateway() [3/5]

eoGateway::eoGateway ( eoPacketStream * str )

Creates your EnOcean gateway class.

Parameters

str	- creates a Gateway with a specified eoPacketStream.

◆ eoGateway() [4/5]

eoGateway::eoGateway	(	eoPacketStream *	str,
		eoDeviceManager *	devManager
	)

Creates your EnOcean gateway class.

Parameters

str	- creates a Gateway with a specified eoPacketStream.
devManager	- creates a Gateway with a specified eoDeviceManager.

◆ eoGateway() [5/5]

eoGateway::eoGateway	(	eoPacketStream *	str,
		eoDeviceManager *	devManager,
		eoIFilter *	normFilter,
		eoIFilter *	lrnFilter
	)

Creates your EnOcean gateway class.

Parameters

str	- creates a Gateway with a specified eoPacketStream.
devManager	- creates a Gateway with a specified eoDeviceManager.
normFilter	- creates a Gateway with a specified filter for data communication.
lrnFilter	- creates a Gateway with a specified filter for learn process.

Member Function Documentation

◆ Close()

void eoGateway::Close ( )

Closes the connection.

Examples:: genericProfile_examples.cpp.

◆ Open()

eoReturn eoGateway::Open ( const char * port )

Tries to open a connection to the specified Port

Parameters

port	to open; for example "/dev/ttyUSB0"

Returns: eoReturn EO_OK if everything was ok else PORT_ERROR

Examples:: commands_example.cpp, Gateway_example.cpp, Gateway_SubtypeExample.cpp, GatewayFiltered_example.cpp, genericProfile_examples.cpp, HelloWorld.cpp, Security_example.cpp, sendTelegram_example.cpp, tutorial1.cpp, tutorial2.cpp, tutorial3.cpp, tutorial4.cpp, tutorial5.cpp, tutorial6.cpp, vld_example.cpp, and WatcherMain.cpp.

◆ Receive()

uint16_t eoGateway::Receive ( )

Handles received Telegrams.

The receive function handles all incoming Packets.
Depending if we're in LearnMode or not the handling differs. In normal mode:

When a packet has been received (RECV_PACKET), it automatically tries to decode as much as possible from the Packet.
If the Packet contains a Telegram the Telegram variable will be filled if it is not filtered from the filter, (RECV_TELEGRAM)
If the Packet contains a ERP2 Telegram the Telegram variable will be filled if it is not filtered from the filter, (RECV_ERP2_TELEGRAM)
If the Telegram is a chained Message or a valid standalone telegram, the message will be filled(RECV_MESSAGE)
If the Telegram is secured and the device is learn_in the telegram will be decrypted (RECV_TELEGRAM_SEC)
If the Telegram is from a learned in EEP or GP Device the profile Information will be set (RECV_PROFILE)

In LearnMode data will handled as in normal mode but the learnFilter will be used to Filter telegram & Devices will be learned in as specified in the [EEP] or [GP] document.

When a second 4BS or 1BS Teach IN telegram from the same devices gets received, the RECV_SECTEACHIN flag will be set.

If you're in normal mode, a RECV_TEACHIN flag will be set for 4BS and 1BS Teach IN telegrams, but the device&&profile will not be learned in!

Note: the RECV_TEACHIN flag is set, so that the user can implement his own learn IN System

*

Note: To be sure that no telegram gets missed, ensure that eoGateway::Receive() is called at least once every 100ms.

Returns: RECEIVE_FLAGS

Examples:: Gateway_example.cpp, Gateway_SubtypeExample.cpp, GatewayFiltered_example.cpp, genericProfile_examples.cpp, HelloWorld.cpp, tutorial1.cpp, tutorial2.cpp, tutorial3.cpp, tutorial4.cpp, tutorial6.cpp, vld_example.cpp, and WatcherMain.cpp.

◆ Send() [1/4]

virtual eoReturn eoGateway::Send ( const eoPacket & p )

virtual

sends Packet to the connected device

Note: the Gateway waits for a Response, as defined in the ESP3 for maximal 500ms! In the worst case you need to wait for such a long time

Parameters

p	Packet to send

Returns: eoReturn

Examples:: genericProfile_examples.cpp, Security_example.cpp, sendTelegram_example.cpp, tutorial1.cpp, tutorial2.cpp, tutorial3.cpp, tutorial6.cpp, and vld_example.cpp.

◆ Send() [2/4]

virtual eoReturn eoGateway::Send ( const eoMessage & msg )

virtual

sends a Message via the connected device

Parameters

msg	Message to send

Returns: eoReturn

◆ Send() [3/4]

virtual eoReturn eoGateway::Send	(	const eoReManMessage &	reMsg,
		bool	shallBeRepeated = `false`,
		uint8_t	keyToUse = `0`
	)

virtual

sends a Message via the connected device

Parameters

reMsg	Remote Management Message to send
set	repeat flag
encrypt	the reman message using key 1-15 (0 means unsecured)

Returns: eoReturn

◆ Send() [4/4]

virtual eoReturn eoGateway::Send ( const eoMaintenanceMessage & manMsg )

virtual

This sends an eoMaintenanceMessage via the Connected Device. The gateway automatically tries to encrypt the Message if the Destination ID is a know Device (in the deviceManager), and it is "decrypted",

Parameters

manMsg Maintenance Message to send

Returns: eoReturn

◆ Serialize()

uint8_t eoGateway::Serialize ( eoArchive & arch )

virtual

Serialization Function which will be called by the eoStorageManager.

This function will be called by the eoArchive(inside of the eoStorageManager) and allows the class to be Serialized.

Parameters

arch	archive where to Load or to Store.

Implements eoISerialize.

Member Data Documentation

◆ device

eoDevice* eoGateway::device

Pointer to the device, to which the last received Telegram belongs.

Note: could be a NULL Pointer!!!

Examples:: Gateway_example.cpp, Gateway_SubtypeExample.cpp, GatewayFiltered_example.cpp, genericProfile_examples.cpp, tutorial1.cpp, tutorial2.cpp, tutorial3.cpp, tutorial6.cpp, vld_example.cpp, and WatcherMain.cpp.

◆ filter

eoIFilter* eoGateway::filter

when this Filter points to a Filter implementation, the received telegram will be filtered while not in learn Mode.

Note: To use no filter, filter=NULL

Examples:: GatewayFiltered_example.cpp, sendTelegram_example.cpp, tutorial1.cpp, tutorial6.cpp, and vld_example.cpp.

◆ learnFilter

eoIFilter* eoGateway::learnFilter

This filter will bes used in learnMod

Note: To use no filter, filter=NULL

Examples:: GatewayFiltered_example.cpp, tutorial1.cpp, and tutorial6.cpp.

◆ maintenanceMessage

eoMaintenanceMessage eoGateway::maintenanceMessage

received Maintenance Message

Note: contains the last received data!#

◆ message

eoMessage eoGateway::message

received Message

Note: contains the last received data!

Examples:: genericProfile_examples.cpp, tutorial1.cpp, tutorial4.cpp, and tutorial6.cpp.

◆ packet

eoPacket eoGateway::packet

received Packet data

Note: contains the last received data!

Examples:: Gateway_example.cpp, Gateway_SubtypeExample.cpp, and vld_example.cpp.

◆ reManMessage

eoReManMessage eoGateway::reManMessage

received Remote Management Message

Note: contains the last received data!#

◆ telegram

eoTelegram eoGateway::telegram

received Telegram

Note: contains the last received data!

Examples:: Gateway_example.cpp, Gateway_SubtypeExample.cpp, GatewayFiltered_example.cpp, genericProfile_examples.cpp, HelloWorld.cpp, tutorial1.cpp, tutorial6.cpp, vld_example.cpp, and WatcherMain.cpp.

◆ telegramERP2

eoTelegramERP2 eoGateway::telegramERP2

received Telegram

Note: contains the last received data!

Examples:: Gateway_example.cpp, Gateway_SubtypeExample.cpp, and HelloWorld.cpp.

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ eoGateway() [1/5]

◆ eoGateway() [2/5]

◆ eoGateway() [3/5]

◆ eoGateway() [4/5]

◆ eoGateway() [5/5]

Member Function Documentation

◆ Close()

◆ Open()

◆ Receive()

◆ Send() [1/4]

◆ Send() [2/4]

◆ Send() [3/4]

◆ Send() [4/4]

◆ Serialize()

Member Data Documentation

◆ device

◆ filter

◆ learnFilter

◆ maintenanceMessage

◆ message

◆ packet

◆ reManMessage

◆ telegram

◆ telegramERP2