Docs

You are here:
Connection

Detailed Description

Structure RCMConnection represents a single connection with a RCM radio module.

The RCMConnection is the main element of the RCM library.

Data Structures

struct  RCMPERTestResult
 
struct  RCMFirmwareVersion
 node's firmware version More...
 
struct  RCMTimeSync
 
struct  RCMConnection
 

Typedefs

typedef void(* RCMNeighborhoodIndicationCallback )(struct RCMConnection *rcm, RCMLINK_NeigborhoodIndicationHeader *header, RCMLINK_NeigborhoodIndicationRecord *neighbors)
 
typedef void(* RCMPERTestCallback )(struct RCMConnection *rcm, RCMPERTestResult *result)
 
typedef int64_t(* RCM_GetTimeFunc )(void)
 
typedef void(* RCM_SetTimeFunc )(int64_t)
 
typedef struct RCMConnection RCMConnection
 

Enumerations

enum  RCMPHY { RCM_PHY_20KBPS = 0, RCM_PHY_100KBPS = 2 }
 
enum  RCMAntenna { RCM_ANT1 = 0, RCM_ANT2 = 1, RCM_ANT1_DIVERSITY = 2, RCM_ANT2_DIVERSITY = 3 }
 
enum  RCMDeviceType { RCM_DEVICE_TYPE_COORDINATOR = 0, RCM_DEVICE_TYPE_ROUTER = 1, RCM_DEVICE_TYPE_END_DEVICE = 2 }
 
enum  RCMAddressingScheme { RCM_ADDRESSING_SCHEME_STOCHASTIC = 0, RCM_ADDRESSING_SCHEME_STATIC = 1 }
 
enum  RCMNetworkState {
  RCM_NETWORK_UNKNOWN_STATE = 0, RCM_NETWORK_INIT = 1, RCM_NETWORK_IDLE = 2, RCM_NETWORK_JOINING = 3,
  RCM_NETWORK_JOINED = 4, RCM_NETWORK_LEAVING = 5, RCM_NETWORK_LEFT = 6, RCM_NETWORK_STANDBY = 7,
  RCM_NETWORK_WAKING = 8, RCM_NETWORK_ERROR = 127
}
 
enum  RCMAddressingMode {
  RCM_ADDR_MODE_NO_ADDRESS, RCM_ADDR_MODE_GROUP_ADDRESS, RCM_ADDR_MODE_SHORT_ADDRESS, RCM_ADDR_MODE_UID,
  RCM_ADDR_MODE_BROADCAST
}
 
enum  RCMonfirmationMode { RCM_NO_ACK = 0, RCM_ACK }
 
enum  RCMOutputPowerTestMode { CARRIER_WAVE = 0, PSEUDO_RANDOM_BIT_SEQUENCE = 1 }
 
enum  RCMLogChannel { RCM_LOG_CHANNEL_APP = 0, RCM_LOG_CHANNEL_SCOM = 1, RCM_LOG_CHANNEL_RCMLINK = 2 }
 
enum  RCMNTS_DeviceType { RCMNTS_SERVER, RCMNTS_ROUTER, RCMNTS_CLIENT }
 
enum  RCMResult {
  RCM_RESULT_OK, RCM_RESULT_INVALID_PARAMETER, RCM_RESULT_FAILED_TO_INITIALIZE_IODEVICE, RCM_RESULT_FAILED_TO_INITIALIZE_SCOM,
  RCM_RESULT_FAILED_TO_INITIALIZE_BUFFER, RCM_RESULT_FAILED_TO_INITIALIZE_SCOM_FILTERING, RCM_RESULT_FAILED_TO_INITIALIZE_FRAME_MATCH_FILTER, RCM_RESULT_FAILED_TO_INITIALIZE_SERVICE_FILTER,
  RCM_RESULT_FAILED_TO_INITIALIZE_DATA_INDICATION_FILTER, RCM_RESULT_FAILED_TO_INITIALIZE_NEIGHBORHOOD_INDICATION_FILTER, RCM_RESULT_FAILED_TO_INITIALIZE_PER_TEST_FILTER, RCM_RESULT_FAILED_TO_PROBE_DEVICE,
  RCM_RESULT_FAILED_TO_CREATE_MUTEX, RCM_RESULT_FAILED_TO_CREATE_SEMAPHORE, RCM_RESULT_FAILED_TO_CREATE_TASK, RCM_RESULT_FAILED_TO_TERMINATE_TASK,
  RCM_RESULT_SCOM_TRANSACTION_ERROR, RCM_RESULT_MODEM_COMMUNICATION_ERROR, RCM_RESULT_MODEM_COMMUNICATION_TIMEOUT, RCM_RESULT_FAILED_TO_LOCK_TRANSFER_DESCRIPTOR,
  RCM_RESULT_BUSY, RCM_RESULT_FAILED, RCM_RESULT_ERROR
}
 

Initializing and running the connection

The following functions are used to initialize, run and deinitialize the connection with radiomodem.

RCMResult RCM_Reset (IODevice iodev, const char *resetMethod)
 
RCMResult RCM_Open (RCMConnection *rcm, IODevice iodev, SCOMFrameBuffer *scomFrameBuffer, RCMMessageBuffer *messageBuffer, SCOMClockSource clockSource)
 
RCMResult RCM_Close (RCMConnection *rcm)
 
RCMResult RCM_CommunicationProc (RCMConnection *rcm)
 
void RCM_FilterProc (RCMConnection *rcm)
 
RCMResult RCM_Run (RCMConnection *rcm)
 
RCMResult RCM_Stop (RCMConnection *rcm)
 
RCMResult RCM_GetConnectionState (RCMConnection *rcm)
 

Configuring the radio module.

The following functions are used to configure various parameters of a radio module.

RCMResult RCM_GetMaxPayloadSize (RCMConnection *rcm, uint8_t *maxPayloadSize)
 
RCMResult RCM_SetConfiguration (RCMConnection *rcm, RCMDeviceType deviceType, uint64_t panId, RCMAddressingScheme addressingScheme, uint16_t nwkAddr)
 
RCMResult RCM_GetConfiguration (RCMConnection *rcm, RCMDeviceType *deviceType, uint64_t *panId, RCMAddressingScheme *addressingScheme, uint16_t *nwkAddr)
 
RCMResult RCM_SetUID (RCMConnection *rcm, uint64_t uid)
 
RCMResult RCM_GetUID (RCMConnection *rcm, uint64_t *uid)
 
RCMResult RCM_SetOutputPower (RCMConnection *rcm, int8_t outputPowerIndBm)
 
RCMResult RCM_GetOutputPower (RCMConnection *rcm, int8_t *outputPowerIndBm)
 
RCMResult RCM_SetAntenna (RCMConnection *rcm, RCMAntenna antennaNo)
 
RCMResult RCM_SetPHY (RCMConnection *rcm, RCMPHY phy, uint32_t channelMask)
 
RCMResult RCM_GetPHY (RCMConnection *rcm, RCMPHY *phy, uint32_t *channelMask)
 
RCMResult RCM_EnableNetworkSecurity (RCMConnection *rcm, const void *nwkKey)
 

Running in a network

The following functions are used to control network operation.

RCMResult RCM_StartNetworking (RCMConnection *rcm)
 
RCMResult RCM_StopNetworking (RCMConnection *rcm)
 
RCMResult RCM_GetNetworkState (RCMConnection *rcm, RCMNetworkState *networkState)
 
RCMResult RCM_GetUIDFromNwkShort (RCMConnection *rcm, uint16_t nwkShortAddr, uint64_t *uid, OSTime timeout)
 
RCMResult RCM_GetNwkShortFromUID (RCMConnection *rcm, uint64_t uid, uint16_t *nwkAddr, OSTime timeout)
 

Data exchange

The following functions are used for data exchange.

RCMResult RCM_RegisterEndpoint (RCMConnection *rcm, uint8_t endpointNo)
 
RCMResult RCM_AddEndpointToGroup (RCMConnection *rcm, uint8_t endpoint, uint16_t groupAddr)
 
RCMResult RCM_SendMessage (RCMConnection *rcm, RCMMessage *msg)
 
RCMMessageRCM_GetPendingMessage (RCMConnection *rcm)
 
void RCM_UnlockMessage (RCMConnection *rcm, RCMMessage *message)
 

Performance testing

The following functions are used for output power and packet error rate tests.

RCMResult RCM_StartContinuousTX (RCMConnection *rcm, RCMOutputPowerTestMode mode, uint8_t outputNo)
 
RCMResult RCM_StartPERTest (RCMConnection *rcm, uint16_t interval, uint16_t totalPackets, uint16_t shortAddr, uint32_t *testId)
 
RCMResult RCM_WaitForPERTestEnd (RCMConnection *rcm, uint32_t testId, RCMPERTestResult *testResult, OSTime timeout)
 
RCMResult RCM_GetPERTestResult (RCMConnection *rcm, uint32_t testId, RCMPERTestResult *testResult)
 
RCMResult RCM_GetPERTestResultFromRemoteNode (RCMConnection *rcm, uint16_t shortAddr, uint32_t testId, RCMPERTestResult *testResult, OSTime timeout)
 
void RCM_SetPERTestCallback (RCMConnection *rcm, RCMPERTestCallback callback)
 

Debug output control

The following functions are used to control the debug log from the radiomodem.

RCMResult RCM_EnableLogOutput (RCMConnection *rcm)
 
RCMResult RCM_DisableLogOutput (RCMConnection *rcm)
 
RCMResult RCM_EnableLogChannel (RCMConnection *rcm, RCMLogChannel logChannel)
 
RCMResult RCM_DisableLogChannel (RCMConnection *rcm, RCMLogChannel logChannel)
 

Sleep mode

The following functions are used to enter and exit sleep mode.

RCMResult RCM_Sleep (RCMConnection *rcm)
 
RCMResult RCM_Wakeup (RCMConnection *rcm)
 
RCMResult RCM_WakeupWithNeighborhoodIndication (RCMConnection *rcm)
 

Neighborhood indication

The following functions are used to control the automatic sending of neighborhood indication.

void RCM_SetNeighborhoodIndicationCallback (RCMConnection *rcm, RCMNeighborhoodIndicationCallback callback)
 
RCMResult RCM_SetNeighborhoodIndicationInterval (RCMConnection *rcm, uint32_t interval)
 
RCMResult RCM_GetNeighborhoodIndicationInterval (RCMConnection *rcm, uint32_t *interval)
 
RCMResult RCM_SendNeighborhoodIndication (RCMConnection *rcm)
 

Firmware update

The following functions are used to manage firmware updates and versioning.

RCMResult RCM_GetFirmwareVersion (RCMConnection *rcm, uint8_t *verHi, uint8_t *verLo, uint32_t *revision)
 
RCMResult RCM_WriteFirmwareUpdate (RCMConnection *rcm, uint32_t offset, const void *data, size_t size)
 
RCMResult RCM_ReadFirmwareUpdate (RCMConnection *rcm, uint32_t offset, void *data, size_t size)
 

Typedef Documentation

typedef int64_t(* RCM_GetTimeFunc)(void)

Type of user callback function that returns current system time as timestamp represented in milliseconds elapsed since epoch specified by time-sync service.

typedef void(* RCM_SetTimeFunc)(int64_t)

Type of user callback function that takes timestamp represented in milliseconds elapsed since epoch specified by time-sync service and accordingly sets current system time.

typedef struct RCMConnection RCMConnection

Descriptor of the connection.

typedef void(* RCMNeighborhoodIndicationCallback)(struct RCMConnection *rcm, RCMLINK_NeigborhoodIndicationHeader *header, RCMLINK_NeigborhoodIndicationRecord *neighbors)

Definition of function that will be a neighborhood indication callback.

typedef void(* RCMPERTestCallback)(struct RCMConnection *rcm, RCMPERTestResult *result)

Definition of function that will be called whenever a PER test result is received

Enumeration Type Documentation

Possible message addressing modes.

Enumerator
RCM_ADDR_MODE_NO_ADDRESS 

Indirect addressing mode via binding feature.

RCM_ADDR_MODE_GROUP_ADDRESS 

Group addressing mode via multicast.

RCM_ADDR_MODE_SHORT_ADDRESS 

Unicast addressing mode by 16-bit network address.

RCM_ADDR_MODE_UID 

Unicast addressing mode by 64-bit IEEE address.

RCM_ADDR_MODE_BROADCAST 

Unicast addressing mode by 16-bit network address, with message confirmation.

Possible network device addressing schemes - these control how short (16bit) network addresses are assigned to nodes.

Enumerator
RCM_ADDRESSING_SCHEME_STOCHASTIC 

Stochastic addressing - the nodes will have random short network addresses.

RCM_ADDRESSING_SCHEME_STATIC 

Static addressing - the nodes will have a predefined short network address.

Possible network device types.

Enumerator
RCM_DEVICE_TYPE_COORDINATOR 

Network device is the coordinator.

RCM_DEVICE_TYPE_ROUTER 

Network device is a router.

RCM_DEVICE_TYPE_END_DEVICE 

Network device is an end device.

Possible debug log channels.

Enumerator
RCM_LOG_CHANNEL_APP 

General application log channel.

RCM_LOG_CHANNEL_SCOM 

SCOM log channel.

RCM_LOG_CHANNEL_RCMLINK 

RCMLINK log channel.

Possible network states.

Provides types of devices using in Time Sync Service

Possible type of acknowledge sending a message.

Enumerator
RCM_NO_ACK 

Only indicate end of sending procedure.

RCM_ACK 

Request for acknowledgment of successful delivery.

Possible signals for the output power test mode.

Enumerator
CARRIER_WAVE 

Carrier wave at Fc - 0.1MHz.

PSEUDO_RANDOM_BIT_SEQUENCE 

Pseudo random sequence.

enum RCMPHY

Possible PHY types.

Enumerator
RCM_PHY_20KBPS 

BPSK-20kbps.

RCM_PHY_100KBPS 

O-QPSK-100kbps.

enum RCMResult

Possible RCM results.

Function Documentation

RCMResult RCM_AddEndpointToGroup ( RCMConnection rcm,
uint8_t  endpoint,
uint16_t  groupAddr 
)

Associates an endpoint with a given group.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
endpointendpoint number
groupAddr16-bit group address
RCMResult RCM_Close ( RCMConnection rcm)

Closes the connection with a RCMLINK radio module, that was previously opened by a call to RCM_Open.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Returns
always RCM_RESULT_OK
RCMResult RCM_CommunicationProc ( RCMConnection rcm)

This function should be called periodically on an open connection (see RCM_Open) in order to process the communication with a RCMLINK radio module. Internally, this function calls SCOM_Proc to process the SCOM communication protocol engine.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKif processing returned no error and connection is still operational
RCM_RESULT_MODEM_COMMUNICATION_ERRORif connection with the RCMLINK radio modem was broken
RCM_RESULT_INVALID_PARAMETERif the supplied connection descriptor is bad
RCMResult RCM_DisableLogChannel ( RCMConnection rcm,
RCMLogChannel  logChannel 
)

Disables the given diagnostic channel output in the radiomodem.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
logChanneldiagnostic channel to disable
Return values
RCM_RESULT_OKwhen the operation succeeded and the given log channel was disabled
RCM_RESULT_FAILEDwhen the test could not be started by modem
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_DisableLogOutput ( RCMConnection rcm)

Disables the log output from the radiomodem.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKwhen the operation succeeded and the debug log was disabled
RCM_RESULT_FAILEDwhen the log output could not be disabled
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_EnableLogChannel ( RCMConnection rcm,
RCMLogChannel  logChannel 
)

Enables the given diagnostic channel output in the radiomodem.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
logChanneldiagnostic channel to enable
Return values
RCM_RESULT_OKwhen the operation succeeded and the given log channel was enabled
RCM_RESULT_FAILEDwhen the test could not be started by modem
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_EnableLogOutput ( RCMConnection rcm)

Enables the log output from the radiomodem.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKwhen the operation succeeded and the debug log was enabled
RCM_RESULT_FAILEDwhen the log output could not be enabled
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_EnableNetworkSecurity ( RCMConnection rcm,
const void *  nwkKey 
)

Enables network security with a given network key.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
nwkKey128-bit network key
Return values
RCM_RESULT_OKif the network security was enabled
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
void RCM_FilterProc ( RCMConnection rcm)

Runs the SCOM filter processing. Should be called periodically. Internally calls the SCOM_FilterProc function.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
RCMResult RCM_GetConfiguration ( RCMConnection rcm,
RCMDeviceType deviceType,
uint64_t *  panId,
RCMAddressingScheme addressingScheme,
uint16_t *  nwkAddr 
)

Retrieves network parameters of a radiomodem.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
deviceTypepointer to a variable where type of device (coordinator, router or end-device) will be stored
panIdpointer to a variable where network identifier will be stored
addressingSchemepointer to a variable where addressing scheme (static or stochastic) will be stored
nwkAddrpointer to a variable where short network address will be stored
Return values
RCM_RESULT_OKwhen the operation succeeded and the configuration was sent to radiomodem.
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetConnectionState ( RCMConnection rcm)

Gets information about current connection state.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKif connection is fully operational
RCM_RESULT_MODEM_COMMUNICATION_ERRORif connection is broken
RCM_RESULT_INVALID_PARAMETERif the supplied connection descriptor is bad
RCMResult RCM_GetFirmwareVersion ( RCMConnection rcm,
uint8_t *  verHi,
uint8_t *  verLo,
uint32_t *  revision 
)

Gets the version of the firmware currently running on the radio module. The version has the following format: HI.LO.REV where:

HI - is the high version number LO - is the low version number REV - is the revision number

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
verHipointer to a byte, where high version number will be stored
verLopointer to a byte, where low version number will be stored
revisionpointer to a byte, where reversion number will be stored
Return values
RCM_RESULT_OKwhen the operation succeeded and firmware version has been retrieved successfully
RCM_RESULT_FAILEDwhen the operation failed, and firmware version has not been retrieved successfully
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetMaxPayloadSize ( RCMConnection rcm,
uint8_t *  maxPayloadSize 
)

Gets the maximum payload size that can fit a single RCM packet.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
maxPayloadSizepointer to a variable, where the resulting value will be stored
Return values
RCM_RESULT_OKwhen the operation succeeded and the value returned in maxPayloadSize is valid
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetNeighborhoodIndicationInterval ( RCMConnection rcm,
uint32_t *  interval 
)

Gets the currently set value of neighborhood indication interval (see RCM_SetNeighborhoodIndicationInterval).

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
intervalpointer to a variable, where the time interval (in seconds) between indications will be stored
Return values
RCM_RESULT_OKwhen the operation succeeded and interval variable was set to the value configured in the radio module
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetNetworkState ( RCMConnection rcm,
RCMNetworkState networkState 
)

Polls the network state.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
networkStatepointer to a variable, where network state will be stored
Return values
RCM_RESULT_OKwhen the operation succeeded and variable pointed to by networkState contains valid network state read from the modem
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetNwkShortFromUID ( RCMConnection rcm,
uint64_t  uid,
uint16_t *  nwkAddr,
OSTime  timeout 
)

Gets the short network addres of a node with a given UID. This operation requires communication with the destination node.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
uidnode's 64 bit unique identifier of the node, of which we want to get a short network address
nwkAddrpointer to a variable, where short (16-bit) network address will be stored
timeoutmaximum time allowed to wait for the response from the remote node
Return values
RCM_RESULT_OKwhen the operation succeeded and variable pointed to by nwkAddr contains valid short network address of the remote node
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem or network communication timeout
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetOutputPower ( RCMConnection rcm,
int8_t *  outputPowerIndBm 
)

Gets the currently set transceiver output power.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
outputPowerIndBmpointer to a variable, where the value of currently set output power will be stored (in dBm)
Return values
RCM_RESULT_OKif the output power was read successfully
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMMessage* RCM_GetPendingMessage ( RCMConnection rcm)

Gets pending received message, if any. If message is returned, the caller is responsible for deleting it through a call to RCM_UnlockMessage.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Returns
pointer to a pending message object or 0
RCMResult RCM_GetPERTestResult ( RCMConnection rcm,
uint32_t  testId,
RCMPERTestResult testResult 
)

Retrieves PER test result from local node.

The packet error rate (PER) test results, for the test that was started using RCM_StartPERTest are available at both nodes that took part in the test - the local node and the remote node. This function gathers results from local node. The test is identified by a 32-bit identifier, that is returned by the RCM_StartPERTest function.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
testIdid of the PER test
testResultplace to store PER test result
Return values
RCM_RESULT_OKwhen the operation succeeded and the test was initiated
RCM_RESULT_FAILEDwhen the test results could not be retrieved
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetPERTestResultFromRemoteNode ( RCMConnection rcm,
uint16_t  shortAddr,
uint32_t  testId,
RCMPERTestResult testResult,
OSTime  timeout 
)

Retrieves PER test results from remote node.

The packet error rate (PER) test results, for the test that was started using RCM_StartPERTest are available at both nodes that took part in the test - the local node and the remote node. This function gathers results from local node. The test is identified by a 32-bit identifier, that is returned by the RCM_StartPERTest function. The process of retrieving results from remote node requires radio communication, thus a maximum time waiting for the response must be given (timeout).

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
shortAddrshort network address of the remote node from which the results are gathered
testIdtest id
testResultplace to store results
timeoutmaximum time (in ms) waiting for results
Return values
RCM_RESULT_OKwhen the operation succeeded and the test was initiated
RCM_RESULT_FAILEDwhen the test could not be started by modem
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetPHY ( RCMConnection rcm,
RCMPHY phy,
uint32_t *  channelMask 
)

Gets the currently set physical layer options.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
phypointer to a variable, where physical layer type will be stored
channelMaskpointer to a variable, where channel mask will be stored
Return values
RCM_RESULT_OKwhen the operation succeeded and PHY options were read successfully
RCM_RESULT_FAILEDwhen the node could not get the given PHY options
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetUID ( RCMConnection rcm,
uint64_t *  uid 
)

Gets the device's unique identifier (UID). This identifier is actually an IEEE 64-bit MAC address of the node, sometimes also called an Extended Address. The UID must be unique and shall not be 0.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
uidpointer to a variable where the read 64 bit unique identifier used as an IEEE 64 bit MAC address (a.k.a. extended address) will be stored
Return values
RCM_RESULT_OKwhen the operation succeeded and the variable pointed to by uid contains a vaild node UID
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed and the UID could not be read
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_GetUIDFromNwkShort ( RCMConnection rcm,
uint16_t  nwkShortAddr,
uint64_t *  uid,
OSTime  timeout 
)

Gets the UID of a node with a given short network address. This operation requires communication with the destination node.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
nwkShortAddrshort (16-bit) network address of the node, of which we want to get an UID
uidpointer to a variable where the node's 64 bit unique identifier will be stored
timeoutmaximum time allowed to wait for the response from the remote node
Return values
RCM_RESULT_OKwhen the operation succeeded and variable pointed to by uid contains valid UID of the remote node
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem or network communication timeout
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_Open ( RCMConnection rcm,
IODevice  iodev,
SCOMFrameBuffer scomFrameBuffer,
RCMMessageBuffer messageBuffer,
SCOMClockSource  clockSource 
)

Opens connection with a RCMLINK radio module. The connection internally uses the SCOM protocol to exchange messages with the RCMLINK radio module in a reliable way.

This function initializes and configures the IODevice used for communication with radio module. Next it initializes the SCOM connection including SCOM frame filtering mechanisms, as well as required synchronization mechanisms. This function however does not attempt to exchange any information with the radio module, so successful opening of the connection does not guarantee that the connection will be operational.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
iodevIODevice used for communication with the radio module
scomFrameBufferpointer to SCOM frame buffer structure (see SCOMFrameBuffer)
messageBufferpointer to RCM message buffer structure (see RCM_MessageBuf)
clockSourcefunction that will provide clock information (see SCOMClockSource)
Return values
RCM_RESULT_OKwhen the connection was opened successfully
RCM_RESULT_INVALID_PARAMETERif one of the supplied parameters is bad
RCM_RESULT_FAILED_TO_INITIALIZE_SCOMif SCOM initialization failed
RCM_RESULT_FAILED_TO_INITIALIZE_SCOM_FILTERINGif initialization of SCOM filtering mechanism failed
RCM_RESULT_FAILED_TO_INITIALIZE_FRAME_MATCH_FILTERif frame-match filter could not be initialized
RCM_RESULT_FAILED_TO_INITIALIZE_DATA_INDICATION_FILTERif data indication filter could not be initialized
RCM_RESULT_FAILED_TO_INITIALIZE_NEIGHBORHOOD_INDICATION_FILTERif neighborhood indication filter could not be initialized
RCMResult RCM_ReadFirmwareUpdate ( RCMConnection rcm,
uint32_t  offset,
void *  data,
size_t  size 
)

Reads a chunk of firmware data from the firmware update memory buffer.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
offsetoffset of the data
dataplace to store the read data
sizesize (in number of bytes) of the data to read
Return values
RCM_RESULT_OKwhen the operation succeeded and firmware data has been read successfully
RCM_RESULT_FAILEDwhen the operation failed, and firmware data has not been read successfully
RCMResult RCM_RegisterEndpoint ( RCMConnection rcm,
uint8_t  endpointNo 
)

Registers an endpoint.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
endpointNoendpoint number. Valid values span from 1 to 239.
Return values
RCM_RESULT_OKwhen the operation succeeded and the endpoint has been registered
RCM_RESULT_FAILEDwhen the node could not register new endpoint
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_Reset ( IODevice  iodev,
const char *  resetMethod 
)

Resets the RCMLINK radio module by physically applying the reset signal to the module pin.

Parameters
iodevIODevice used for communication with the radio module
resetMethodstring describing how exactly should the reset signal be generated
Return values
RCM_RESULT_OKwhen the reset signal was generated successfully
RCM_RESULT_FAILEDif the reset signal could not be generated
RCMResult RCM_Run ( RCMConnection rcm)

Automates the process of using RCM connection by creating and running the RCM communication threads, including main communication thread (RCM_CommunicationProc) and filter processing thread (RCM_FilterProc).

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKif processing returned no error and connection is still operational
RCM_RESULT_INVALID_PARAMETERif the supplied connection descriptor is bad
RCM_RESULT_FAILED_TO_CREATE_TASKif one of the threads failed to be created
RCM_RESULT_FAILED_TO_CREATE_TASKif one of the required semaphores failed to be created
RCMResult RCM_SendMessage ( RCMConnection rcm,
RCMMessage msg 
)

Sends message to a remote node.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
msgmessage to send (see RCMMessage)
Return values
RCM_RESULT_OKif the message was sent out successfully. Note that this not always means that the message was delivered to it's destination.
RCM_RESULT_FAILEDwhen the node could not send the message
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_SendNeighborhoodIndication ( RCMConnection rcm)

Requests sending of neighborhood indication. This message carries information about all the neighbors of the node in the network. It is sent to the network coordinator, where it can be captured by a callback, set by RCM_SetNeighborhoodIndicationCallback.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKif the neighborhood indication was sent out successfully. Note that this not always means that the message was delivered to it's destination.
RCM_RESULT_FAILEDwhen the node could not send the message
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_SetAntenna ( RCMConnection rcm,
RCMAntenna  antennaNo 
)

Sets the antenna used for communication.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
antennaNoselects which antenna is used for communication
Return values
RCM_RESULT_OKif the antenna was set successfully
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_SetConfiguration ( RCMConnection rcm,
RCMDeviceType  deviceType,
uint64_t  panId,
RCMAddressingScheme  addressingScheme,
uint16_t  nwkAddr 
)

Configures network parameters of a radiomodem.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
deviceTypetype of device (coordinator, router or end-device)
panIdnetwork identifier
addressingSchemeaddressing scheme (static or stochastic)
nwkAddrshort network address used when addresing scheme was set to static
Return values
RCM_RESULT_OKwhen the operation succeeded and the configuration was sent to radiomodem.
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
void RCM_SetNeighborhoodIndicationCallback ( RCMConnection rcm,
RCMNeighborhoodIndicationCallback  callback 
)

Sets up a user-defined callback, that will be called whenever a new neighborhood indication message will be received. This message carries information from nodes about their neighbors and can be used to gather information about network topology. To disable the callback, call this function with NULL callback argument.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
callbackuser defined callback function or NULL to disable the callback
RCMResult RCM_SetNeighborhoodIndicationInterval ( RCMConnection rcm,
uint32_t  interval 
)

Sets the period between automatic sending of neighborhood indication information, which includes information about neighboring nodes. By default, the automatic sending of neighborhood indication is disabled in the module (interval is set to 0).

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
intervaltime interval (in seconds) between indications. Setting this time to 0 disables automatic sending of neighborhood indication.
Return values
RCM_RESULT_OKwhen the operation succeeded and neighborhood indication time interval was set successfully
RCM_RESULT_FAILEDwhen the operation failed, and neighborhood indication time interval was not set
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_SetOutputPower ( RCMConnection rcm,
int8_t  outputPowerIndBm 
)

Sets transceiver output power.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
outputPowerIndBmoutput power in dBm units
Return values
RCM_RESULT_OKif the output power was set successfully
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
void RCM_SetPERTestCallback ( RCMConnection rcm,
RCMPERTestCallback  callback 
)

Sets up a user-defined callback, that will be called whenever a packet error rate (PER) test results arrive. To disable the callback, call this function with NULL callback argument.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
callbackuser defined callback function or NULL to disable the callback
RCMResult RCM_SetPHY ( RCMConnection rcm,
RCMPHY  phy,
uint32_t  channelMask 
)

Sets physical layer options. This can be set anytime BEFORE network starts.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
phyphysical layer type (defines baudrate and modulation scheme)
channelMaskchannel mask
Return values
RCM_RESULT_OKwhen the operation succeeded and PHY was set successfully
RCM_RESULT_FAILEDwhen the node could not set the given PHY options
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_SetUID ( RCMConnection rcm,
uint64_t  uid 
)

Sets the device's unique identifier (UID). This identifier is actually an IEEE 64-bit MAC address of the node, sometimes also called an Extended Address. The UID must be unique and shall not be 0.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
uid64 bit unique identifier used as an IEEE 64 bit MAC address (a.k.a. extended address)
Return values
RCM_RESULT_OKwhen the operation succeeded and the UID was set successfully
RCM_RESULT_ERRORwhen the operation failed and the UID could not be set
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_Sleep ( RCMConnection rcm)

Puts the radio module to a low energy sleep mode. This mode is available only for modules configured as end devices. For routers and coordinators this function returns RCM_RESULT_FAILED, as these devices need to be active all the time. Putting the module to sleep will cause all the API functions to fail until the module is woken up again using RCM_Wakeup or RCM_WakeupWithNeigborhoodIndication. Sometimes, due to network activity the module will be unable to go to sleep, and this function will return RCM_RESULT_BUSY. In this case this function can be called repeatedly until the module is successfully put to sleep.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKwhen the operation succeeded and radio module was put to sleep
RCM_RESULT_BUSYwhen the module is unable to go to sleep right now, due to network (or some other) activity
RCM_RESULT_FAILEDwhen the operation failed, and the radio module was not put to sleep
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_StartContinuousTX ( RCMConnection rcm,
RCMOutputPowerTestMode  mode,
uint8_t  outputNo 
)

Starts continuous transmission for output power tests. BEWARE: Enabling continuous radio signal can jam other radio devices in range. This mode must be used with caution and only for evaluation purposes.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
modeoutput signal mode (continuous wave or modulated pseudo-random sequence)
outputNooutput number - for single antenna setups use value of 0, for dual antenna setups values 0 or 1 are valid
RCMResult RCM_StartNetworking ( RCMConnection rcm)

Starts networking activity. As a result the node tries to join an existing network (in case of router or end-device) or start a new network (in case of a coordinator).

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKwhen the operation succeeded and node is part of the network
RCM_RESULT_FAILEDwhen the node could not join the network
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_StartPERTest ( RCMConnection rcm,
uint16_t  interval,
uint16_t  totalPackets,
uint16_t  shortAddr,
uint32_t *  testId 
)

Starts a packet error test. During the test the transceiver will try to send a number of packets (totalPackets) to a remote node identified by short network address (shortAddr). This function only initiates this process which may take some time, depending on the number of packets and time interval between the packets. The test is identified by a 32-bit identifier that is stored in the variable pointed by testId, which can be later used to poll test results by using RCM_GetPERTestResult or RCM_GetPERTestResultFromRemoteNode functions.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
intervalinterval (in ms) between sequential packets
totalPacketsnumber of packets to send
shortAddrshort network address of the destination node
testIdplace to store id of the PER test
Return values
RCM_RESULT_OKwhen the operation succeeded and the test was initiated
RCM_RESULT_FAILEDwhen the test could not be started by modem
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_Stop ( RCMConnection rcm)

Stops the threads created through a call to RCM_Run.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKif processing returned no error and connection is still operational
RCM_RESULT_INVALID_PARAMETERif the supplied connection descriptor is bad
RCM_RESULT_FAILED_TO_TERMINATE_TASKif one of the threads failed to terminate
RCMResult RCM_StopNetworking ( RCMConnection rcm)

Stop all networking activity. As a result the node disconnects from the network.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKwhen the operation succeeded and node disconnected successfully from the network
RCM_RESULT_FAILEDwhen the node could not disconnect from the network
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
void RCM_UnlockMessage ( RCMConnection rcm,
RCMMessage message 
)

Deletes a message that was returned by RCM_GetPendingMessage.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
messagepointer to message that will be deleted
RCMResult RCM_WaitForPERTestEnd ( RCMConnection rcm,
uint32_t  testId,
RCMPERTestResult testResult,
OSTime  timeout 
)

Waits for the end of PER test, previously started by a call to RCM_StartPERTest. The test is identified by a 32-bit identifier, that is returned by the RCM_StartPERTest function. Once the test is finished, the gathered local results are passed through the testResult parameter. The packet error rate (PER) test results, for the test that was started using RCM_StartPERTest are available at both nodes that took part in the test

  • the local node and the remote node. This function gathers results from local node.
Parameters
rcmpointer to a RCMConnection structure, that describes the connection
testIdid of the PER test
testResultplace to store PER test result
timeoutmaximum time allowed to wait for the test end
Return values
RCM_RESULT_OKwhen the test has ended
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the test did not end in the given timeout
RCM_RESULT_FAILEDif the waiting operation could not been proceeded
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_Wakeup ( RCMConnection rcm)

Wakes up a radio module from a low energy sleep mode, set through a previous call to RCM_Sleep. The module will not automatically enter the sleep mode again. To put the module back to sleep use the RCM_Sleep function.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKwhen the operation succeeded and radio module was woken up
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_WakeupWithNeighborhoodIndication ( RCMConnection rcm)

Wakes up a radio module from a low energy sleep mode, set through a previous call to RCM_Sleep. In addition the module is forced to send away neighborhood indication with the information about it's neighbors. If the module has configured a non-zero automatic neighborhood indication interval (using RCM_SetNeighborhoodInterval) a call to this function resets the interval time keeper, so that the next indication will be sent after another full time interval, starting from the time this function is called. The module will not automatically enter the sleep mode again. To put the module back to sleep use the RCM_Sleep function.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
Return values
RCM_RESULT_OKwhen the operation succeeded and radio module was woken up
RCM_RESULT_MODEM_COMMUNICATION_TIMEOUTwhen the operation failed due to communication problem with the modem
RCM_RESULT_INVALID_PARAMETERif at least one of the provided arguments was invalid
RCMResult RCM_WriteFirmwareUpdate ( RCMConnection rcm,
uint32_t  offset,
const void *  data,
size_t  size 
)

Writes a chunk of firmware data to the firmware update memory buffer.

Parameters
rcmpointer to a RCMConnection structure, that describes the connection
offsetoffset of the data
datadata to write
sizesize (in number of bytes) of the data to write
Return values
RCM_RESULT_OKwhen the operation succeeded and firmware data has been written successfully
RCM_RESULT_FAILEDwhen the operation failed, and firmware data has not been written successfully
Go to Top