1. Index

1. Index
2. Overview
3. Instantiation
4. Setup and Configuration
5. Registration
6. Events
7. Function Set
8. Structures
9. Known Issues


2. Overview

The DECT API is a library developed in C++ targeted for the Arduino. This library implements the interface between the Arduino and the DECT Shield. The library functions are separated in six groups as illustrated bellow.

DECT API Overview

Each group deals with different functionalities supported by the shield:


3. Instantiation

The library comes in two flavours: with events and without events. Events use the INT0 external interrupt pin from the Arduino to generate calls to predefined functions when something important is triggered in the shield (e.g. data packet received). Using events consumes more programming space and all functions are executed atomically. If the library is also going to be used in interrupts, then it is necessary to initialize the API with events even if they are not used.

The code bellow demonstrates how to instantiate the DECT class with and without events. The class contains the necessary methods and variables to interact with the DECT Shield.

DECTEvents is just an extension of the DECT class, therefore the functions are the same. See the Events section for more information.


4. Setup and Configuration

The shield is normally configured in the Arduino setup() function, but it can also be configured during normal operation in the loop() function. It is highly recommended to reset the shield in the setup function in order to have the shield with the default settings. Afterwards, configurations are applied using the GetConfigs and SetConfigs functions like exemplified bellow.

The Arduino does not contain any information about the DECT Shield (e.g. status, configurations, etc.), only the means to acquire or change it. The GetConfigs function is used to fill the stConfigs structure with the shield current configurations. In the example above, the function is being executed after a reset, so the default shield settings will be copied. After the structure is modified with the desired configurations, they are applied using the SetConfigs function. A list of the default configurations is shown next.

The API contains individual functions to change specific configurations without using GetConfigs and SetConfigs everytime.

For a simple DECT link between two shields, one needs to be configured as a fixed part and the other as a portable part. This is achieved using two different shield firmwares. Firmware selection is persistent and can be changed using the SetFirmware function illustrated bellow. A shield reset is required to apply the firmware changes. After a firmware change, it is highly recommended to reset the shield settings using the Defaults function.


5. Registration

Before any audio or data transference, the shield working as portable part needs be registered to a fixed part. The fixed part can enable registration using the Register function and the portable part can use the Scan function to start scanning for fixed parts. Afterwards, the GetScanList function is used to retrieve the list of fixed parts which were found. Registration is established when the portable part executes the Register function with the target fixed part identifier, retrieved from GetScanList. Both devices need to have the same pin code before registration, which can be set using the SetPincode function. At any time, the fixed and portable parts can use the GetList function to retrieve the identifiers of all known/registered parts. These identifiers are used in DECT functions to reference other DECT devices or shields.


6. Events

Events allow the Arduino to receive asynchronous interrupts when something important is triggered in the shield (e.g. call slot state change, file stoped playing, etc.). Events can be enabled and toggled by accessing the stEventConfigs structure through GetConfigs and SetConfigs functions. Each event is associated to a group of functionalities and each group can be enabled or disabled, allowing to defined a set of events which can be triggered. Enabling events reserves pin 2, or INT0.

In sketches, it is possible to associate callbacks to each event. When an event is triggered, the corresponding callback is executed asynchronously. See the event functions in the Function Set for more information.


7. Function Set

The DECT API function set is divided in 6 major groups, each targetting different functionalities (Overview section). Bellow are the functions for each group:

7.1. Module Functions

Function: LastError
Arguments: None.
Returns: DECTError - Error code from the last API call.
Description: Returns the last error information from any function in the DECT API.
Code Example:
Function: Version
Arguments: None.
Returns: stVersion - Version structure with the current firmware type and version.
Description: Used to obtain the current shield version and to determine if it is working as a portable or fixed part. See example bellow.
Code Example:
Function: SetFirmware
Arguments: nFirmware - Desired firmware. Can be PP for FP.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Changes the shield firmware to fixed part (FP) or portable part (PP). A restart is required to apply the changes.
Code Example:
Function: Reset
Arguments: None.
Returns: Nothing.
Description: Resets the shield firmware to the default configurations. All previously applied configurations are discarded.
Function: Defaults
Arguments: None.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Resets the shield firmware to the default configurations and also resets the DECT module. This means the registration information, the list of known parts and the pincode will be erased and replaced with the original values.
Function: GetConfigs
Arguments: *pConfigs - Pointer to a stConfigs structure with the configurations to apply.
Returns: Nothing.
Description: Fills the configuration structure with current shield configurations.
Code Example:
Function: SetConfigs
Arguments: *pConfigs - Pointer to a stConfigs structure to hold configurations.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Applies shield configurations from a previously modified stConfigs structure. It is highly recommended to obtain the current shield configurations, with the GetConfigs function, before modifying the structure.
Code Example:
Function: GetStatus
Arguments: *pStatus - Pointer to a stStatus structure to hold current shield status.
Returns: Nothing.
Description: Fills the status structure with current shield status information.
Code Example:

7.2. DECT Functions

Function: GetInfo
Arguments: *pInfo - Pointer to a stInfo structure to hold the RFPI or IPUI.
Returns: Nothing.
Description: Fills the structure with the DECT RFPI, if working as fixed part, or IPUI, if as portable part.
Code Example:
Function: GetPincode
Arguments: *pPincode - Pointer to a stPincode structure to hold the current pincode.
Returns: Nothing.
Description: Fills a structure with the shield current pincode. If the values of fields n5 through n8 in stPincode are 0xF, then the pincode has 4 digits instead of 8.
Code Example:
Function: SetPincode
Args (1): *pInfo - Pointer to a stPincode structure that holds the desired pincode.
Args (2): n1 - First digit of the pincode from 0 to 9.
n2 - Second digit of the pincode from 0 to 9.
n3 - Third digit of the pincode from 0 to 9.
n4 - Fourth digit of the pincode from 0 to 9.
Args (3): n1 - First digit of the pincode from 0 to 9.
n2 - Second digit of the pincode from 0 to 9.
n3 - Third digit of the pincode from 0 to 9.
n4 - Fourth digit of the pincode from 0 to 9.
n5 - Fifth digit of the pincode from 0 to 9.
n6 - Sixth digit of the pincode from 0 to 9.
n7 - Seventh digit of the pincode from 0 to 9.
n8 - Eighth digit of the pincode from 0 to 9.
Returns: true/false - True if the function succeeded, false otherwise.
Description: All three variants of the SetPincode function change the pincode in the shield. The pin can have 4 or 8 digits.
Code Example:
Function: GetList
Arguments: *pList - Pointer to an array of stListElem structures to hold known/registered parts information.
nElements - Number of elements in the pList array.
Returns: uint8_t - Number of elements copied to the array.
Description: Fills the pList array with the list of known associated parts. These can be portable parts if the shield is working as a basestation, or fixed parts if working as a handheld. Each element contains the identifier to reference a certain part, necessary for the remaining DECT functions.
Code Example:
Function: Send
Arguments: nIdentifier - DECT device identifier to where to send the data.
*pData - Pointer to a byte array containing the data to send.
nSize - The size of the data array.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Sends a data packet with up to 54 bytes to another DECT device wirelessly. The nIdentifier argument identifies the target device and can be obtained using the GetList function. If the identifier 0 is used, the packet will be sent to all associated parts.
Code Example:
Function: Recv
Arguments: *pIdentifier - Pointer to a uint8_t to write the sender identifier.
*pData - Pointer to a byte array to write the received data packet.
nSize - The maximum size of the data array.
Returns: The total size of bytes received is returned. Up to 54 bytes.
Description: This function should be called when there is a received data packet in the shield. The packet will be transfered to the Arduino.
Code Example:
Function: Call
Arguments: nIdentifier - Target device identifier. Can be obtained using the GetList function.
eAction - Call action to be executed. See CallAction.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Make, accept, refuse or terminate a call with a target DECT device. See GetCallList function.
Code Example:
Function: GetCallList
Arguments: *pList - Pointer to an array of stCallElem structures to hold call/voice slots information.
nElements - Number of elements in the pList array.
Returns: uint8_t - number of elements copied to the array.
Description: Fills the pList array with the list of all call slots and their correspondent state. Handhelds only have a single call slot, which corresponds to the connected fixed part. It is normal at power up for the function to return 0 until it is possible to communicate with any of the registered parts. Before using Call, it is highly recommended to check if the slot is available. Slot 0 is used to call all known parts if the shield is working as a basestation.
Code Example:
Function: Register
Args(1): nIdentifier - Fixed part identifier to attempt registration. Exclusive for portable parts.
Args(2): true/false - Enable or disable registration, which allows portable parts to detect and register. Exclusive for fixed parts.
Returns: true/false - True if the function succeeded, false otherwise.
Description: For fixed parts, it enables or disables registration mode. For portable parts, it attempts to register to a target fixed part. Use the  GetScanList function to obtain the fixed part identifiers which are in registration mode.
Function: Unregister
Arguments: nIdentifier - Portable part identifier to unregister.
Returns: true/false - True if the function succeeded, false otherwise.
Description: For fixed parts, unregister target portable part. For portable parts, unregister from current fixed part.
Function: Scan
Arguments: true/false - Enable or disable scan mode.
Returns: Nothing.
Description: Exclusive for shields working as portable parts. Enables or disables scanning mode, which enables to detect fixed parts, withing range, with registration enabled by using the GetScanList function.
Function: GetScanList
Arguments: *pList - Pointer to an array of stScanElem structures to hold detected fixed parts information.
nElements - Number of elements in the pList array.
Returns: uint8_t - number of elements copied to the array.
Description: Fills the pList array with the list of detected fixed parts in range with their respective RFPI and RSSI. This function only is valid when the shield is working as a portable part. RSSI can go from 0 (lowest) to 8 (highest).
Code Example:
Function: GetDECTStatus
Arguments: *pStatus - Pointer to a stDECTStatus structure to hold current DECT status.
Returns: Nothing.
Description: Fills the status structure with current DECT status information. Can also be obtained using the GetStatus function.
Code Example:

7.3. Playback Functions

Function: StartPlaying
Arguments: None.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Plays a previously opened file or sequence of files. Files can be opened with the OpenFile function.
Function: StopPlaying
Arguments: None.
Returns: true/false - True if the function succeeded, false otherwise.
Description: If there is a file playing, the audio stream will be stopped.
Function: SetPlaybackVolume
Arguments: nVolume - Playback volume from 0 to 15.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Changes the file playback volume (not the speaker volume) from 0 (muted) to 15 (maximum). This is useful when transmitting audio. Use to SetSpeakerVolume change the speaker/loudspeaker volume instead.
Code Example:
Function: GetPlaybackStatus
Arguments: None.
Returns: stPlaybackStatus - Playback status structure.
Description: Returns the shield’s playback status. This information can also be obtained using the GetStatus function.
Code Example:
Function: SetPlaybackVolume
Arguments: nVolume - Playback volume from 0 to 15.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Changes the file playback volume (not the speaker volume) from 0 (muted) to 15 (maximum). This is useful when transmitting audio. Use to SetSpeakerVolume change the speaker/loudspeaker volume instead.
Code Example:
Function: OpenFile
Arguments: pFilePath - Null-terminated string with the filename and path to be open.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Opens an existing audio file from the memory card. This function always resets the playback queue size to 1. Current shield firmware version only supports 8 kHz WAV files with an 8-bit µ-law encoding.
Code Example:
Function: SetPlaybackQueue
Arguments: nSize - Desired playback queue size.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Change the size of the playback queue.The size of the queue defines the maximum number of files that can be loaded and played in sequence. The shield has to have enough memory to hold the queue. See example from QueueFile.
Function: QueueFile
Arguments: pFilePath - Null-terminated string with the filename and path to be queued.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Opens an existing audio file from the memory card and places it on the bottom of the playback queue. If the queue is full or the file is invalid, the function will return false. Current shield firmware version only supports 8 kHz WAV files with an 8-bit µ-law encoding.
Code Example:
Function: SetPlaybackOutput
Arguments: nOutputs - Target outputs. Can be PB_SPEAKER, PB_DECTLINK or both with a logic OR.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Relays the audio playback stream to a different output. Default is set to go to the shield speaker. Outputs can be the shield speaker and/or a DECT link.
Code Example:

7.4. Audio Functions

Function: SetSpeaker
Arguments: true/false - Enable or disable the speaker output.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Enables or disables the speaker output. Speaker is enabled by default.
Function: SetLoudspeaker
Arguments: true/false - Enable or disable the loudspeaker output.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Enables or disables the loudspeaker output. Loudspeaker is disabled by default.
Function: SetSpeakerVolume
Arguments: nVolume - Desired volume from 0 (-2dB) to 7 (12dB).
Returns: true/false - True if the function succeeded, false otherwise.
Description: Changes the speaker and loudspeaker volume from 0 (-2dB) to 7 (12dB). 0 corresponds to the maximum volume and 7 to the minimum. In reality, the function changes the internal DAC attenuation from -2dB to 12dB in steps of 2dB.
Code Example:
Function: SetMicrophone
Arguments: true/false - Enable or disable the microphone input.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Enables or disables the microphone input. Microphone is enabled by default.
Function: SetMicrophoneGain
Arguments: nGain - Desired gain from 0 (0dB) to 15 (30dB).
Returns: true/false - True if the function succeeded, false otherwise.
Description: Ajusts the microphone sensitivity from 0dB (minimum) to 30dB (maximum) in steps of 2dB.
Code Example:
Function: GetAudioConfigs
Arguments: *pConfigs - Pointer to a stAudioConfigs structure to hold current audio configurations.
Returns: Nothing.
Description: Fills the configuration structure the shield's audio configurations. This information can also be obtained using the GetConfigs function.
Code Example:

7.5. microSD Functions

Function: AccessMicroSD
Arguments: None.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Allows the Arduino to access the microSD card in the shield through SPI. Use DECT_PIN_CSS for the card SPI selection pin (SS).
Function: ReleaseMicroSD
Arguments: None.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Release microSD card access from the Arduino when no longer in use. Highly recommended during audio playback.

7.6. Events Functions

Function: GetEvent
Arguments: *pEvent - Pointer to a pre-allocated stEvent structure to hold an event.
Returns: true/false - True if the function succeeded, false otherwise.
Description: Copies the oldest pending event from the shield to the provided structure. false is returned if no event is present.
Function: attachRecvCallback
Arguments: void (*recv)(uint8_t, uint8_t*, uint8_t) - Pointer to a callback function.
Returns: Nothing.
Description: Attaches a callback to the event triggered when there is a new incoming data packet available in the shield. For the callback to work, the receiver event needs to be enabled using the SetConfigs function. See the bDataEvents field in the stEventConfigs structure and the Events section. See example below for implementation details.
Code Example:
Function: attachCallCallback
Arguments: void (*call)(uint8_t, bool, enum CallState, enum CallState) - Pointer to a callback function.
Returns: Nothing.
Description: Attaches a callback to the event triggered when there call slot changes state. For the callback to work, the call event needs to be enabled using the SetConfigs function. See the bCallEvents field in the stEventConfigs structure and the Events section. See example below for implementation details.
Code Example:
Function: attachPlaybackStoppedCallback
Arguments: void (*pbstop)(void) - Pointer to a callback function.
Returns: Nothing.
Description: Attaches a callback to the event triggered when an audio file finishes playing. For the callback to work, the call event needs to be enabled using the SetConfigs function. See the bPlaybackEvents field in the stEventConfigs structure and the Events section. See example below for implementation details.
Code Example:
Function: attachPlaybackNextCallback
Arguments: void (*pbnext)(uint8_t) - Pointer to a callback function.
Returns: Nothing.
Description: Attaches a callback to the event triggered when there is a playback queue being played and one of the files finishes playing. For the callback to work, the call event needs to be enabled using the SetConfigs function. See the bPlaybackEvents field in the stEventConfigs structure and the Events section. See example below for implementation details.
Code Example:

8. Structures

The API contains several structures and enumerators define. The tree bellow illustrates each struture and their relations.

DECT API
   |- DECTError
   |- stVersion
   |- stConfigs
   |   |- stDECTConfigs
   |   |- stEventConfigs
   |   |- stPlaybackConfigs
   |   |- stAudioConfigs
   |       |- stAudioSpeaker
   |       |- stAudioMic
   |
   |- stStatus
   |   |- stEventStatus
   |   |- stDECTStatus
   |   |   |- stDataStatus
   |   |   |- stCallStatus
   |   |- stPlaybackStatus
   |
   |- stInfo
   |- stPincode
   |- stListElem
   |- CallAction
   |- stCallElem
   |   |- CallState
   |
   |- stScanElem
   |- stEvent
       |- EventType

Structure: enum DECTError
Description: Details an error returned by the LastError function.
Structure: struct stVersion
Description: Holds the shield version and firmware running.
Structure: struct stConfigs
Description: Configuration structure for every component in the shield.
Structure: struct stDECTConfigs
Description: DECT configuration structure. Part of the stConfigs structure.
Structure: struct stEventConfigs
Description: Event configuration structure. Part of the stConfigs structure.
Structure: struct stPlaybackConfigs
Description: Playback configuration structure.  Part of the stConfigs structure.
Structure: struct stAudioConfigs
Description: Audio configuration structure. Part of the stConfigs structure.
Structure: struct stAudioSpeaker
Description: Speaker and loudspeaker configuration structure. Part of the stAudioConfigs structure.
Speaker volume goes from 0 (-2dB) to 7 (12dB) in steps of 2dB.
Structure: struct stAudioMic
Description: Microphone configuration structure. Part of the stAudioConfigs structure.
Microphone gain goes from 0 (0dB) to 15 (30dB) in steps of 2dB.
Structure: struct stStatus
Description: Shield status structure.
Structure: struct stEventStatus
Description: Event status structure. Part of the stStatus structure.
Structure: struct stDECTStatus
Description: DECT status structure. Part of the stStatus structure.
Structure: struct stDataStatus
Description: DECT data status structure. Part of the stDECTStatus structure.
Structure: struct stCallStatus
Description: DECT calls status structure. Part of the stDECTStatus structure.
Structure: struct stPlaybackStatus
Description: Playback status structure. Part of the stStatus structure.
Structure: struct stInfo
Description: DECT identifier structure. A fixed part uses the RFPI and a portable part the IPUI.
Structure: struct stPincode
Description: DECT pincode structure. Fields n5 through n8 are not used if set to 0xF, which means the pincode will have 4 digits.
Structure: struct stListElem
Description: Element from a list of registered parts. A fixed part uses the RFPI and a portable part the IPUI.
Structure: enum CallAction
Description: Enumerator used to execute a call action.
Structure: struct stCallElem
Description: Representation of a DECT voice call slot.
Structure: enum CallState
Description: Enumerator used to indicate a state of a call. Used in the stCallElem structure.
Structure: struct stScanElem
Description: Element from a list of scanned parts. There is no IPUI since only fixed parts are scanned.
Structure: struct stEvent
Description: Represent an event pending in the shield. See EventType for possible events.
Structure: enum EventType
Description: Enumerator used to indicate an event. Used in the stEvent structure.

9. Known Issues