Skip to content

Latest commit

 

History

History
123 lines (83 loc) · 4.48 KB

API.md

File metadata and controls

123 lines (83 loc) · 4.48 KB
Raw

Arduino nRF8001 library API documentation

Setup

The initializer is

nRF8001(uint8_t reset_pin, uint8_t reqn_pin, uint8_t rdyn_pin);

The three arguments indicate the three pins that are specific to each nRF8001 chip. You can have multiple chips attached and each will require 3 pins. The SPI pins (11, 12, and 13) are fixed and can be shared.

nRFCmd setup();

Setup will send the setup messages stored in services.h. This header file is generated by nRFgo Studio and must be stored in the libraries/nRF8001 folder. We ship with a sample services.h file which is Nordic’s heart rate monitor example.

Event handlers

None of the functions that represent a request or command to the nRF8001 immediately return a response. Instead the response is received asynchronously, either the next time a command is transmitted to nRF8001, or by calling poll. When a response is received, any event handlers you have registered will be called.

The exact definition of the event handlers will be listed with the function they belong to. Many commands that do not have an explicit response with data, but only a response indicating whether the command was successful, will call nRFCommandResponseHandler. The definition is:

typedef void (*nRFCommandResponseHandler) (uint8_t opcode, uint8_t status);

opcode is the numeric number for the operation. You may consult constants.h or the nRF8001 datasheet for these numbers. status indicates the result of the command. Of particular interest are NRF_STATUS_SUCCESS for success. Any number above 0x80 is an error. The command response handler is registered with

void setCommandResponseHandler(nRFCommandResponseHandler handler);

There is also the generic event handler nRFEventHandler:

typedef void (*nRFEventHandler) (nRFEvent *);

This event handler will be called on any event received from the nRF8001 and is passed the internal data structure representing the actual bytes received. data.h contains the definition of this data structure.

Polling

The library will receive events from nRF8001 whenever a command or request is transmitted. You may also wait for a response without sending a command with poll.

nRFTxStatus poll(uint16_t timeout);
nRFTxStatus poll();

timeout is a timeout in milliseconds.

State information

uint8_t creditsAvailable();

Data related requests require a “credit” to ensure that data is not sent too fast. creditsAvailable returns the number of available credits.

uint8_t isConnected();

Returns 1 if the device is currently connected to a master, 0 otherwise.

nRFConnectionStatus getConnectionStatus();

Returns connection status. nRFConnectionStatus is an enum with values Disconnected, Connected and Connecting.

uint8_t isPipeOpen(nRFPipe servicePipeNo);

Returns 1 if the specified pipe is currently open, 0 otherwise.

nRFDeviceState getDeviceState();

Returns the device state. nRFDeviceState is an enum defined in constants.h. Most normal operation occurs while in the Standby state.

Device information

nRFTxStatus getBatteryLevel();
void setBatteryLevelHandler(nRFBatteryLevelHandler handler);
typedef void (*nRFBatteryLevelHandler) (float voltage);

Requests battery level from the nRF8001’s ADC. The registered event handler is called with the response, as a floating point number in volts. (The library takes care of the conversion from nRF8001’s internal units.)

nRFTxStatus getTemperature();
void setTemperatureHandler(nRFTemperatureHandler handler);
typedef void (*nRFTemperatureHandler) (float tempC);

Requests temperature from the nRF8001’s on-chip thermometer. The registered event handler is called with the response, as a floating point number in degrees Celcius. (The library takes care of the conversion from nRF8001’s internal units.)

nRFTxStatus getDeviceAddress();
void setDeviceAddressHandler(nRFDeviceAddressHandler handler);
typedef void (*nRFDeviceAddressHandler) (uint8_t *address,
    uint8_t addressType);

Requests the nRF8001 device address. address is a 6 byte long array containing the 48-bit MAC address, unterminated, LSB first. See the nRF8001 datasheet for values of addressType.

nRFTxStatus getDeviceVersion();
void setDeviceVersionHandler(nRFDeviceVersionHandler handler);
typedef void (*nRFDeviceVersionHandler) (uint16_t configId,
    uint8_t aciVersion, uint8_t setupFormat, uint8_t configStatus);

See the nRF8001 datasheet for the meaning of these values.

Connections and data