...
| Code Block |
|---|
|- app -|- app -|- app -|
|------ scheduler ------|
|-- application host ---|------- gateway -------|
|------------------ framework ------------------|
|---------------- util & timer -----------------|
|-------------------- core ---------------------|
|--------------------- HAL ---------------------|
|
Files Critical to Abstraction:
Application/config_notecard_config.hProvides
#definevariables that can be used to force override Notecard specific settings.Application/Framework/sched.hDeclares application callback signatures and the scheduled application configuration structure,
schedAppConfig.Application/Framework/sched.cContains application array, implements the Sparrow task scheduler functions, and performs application callbacks (”Application Host”).
Application/Gateway/auth.cUsed by the gateway to receive/process Notes by adding additional information before forwarding to the Notecard.
Application/Sensor/init.cImplements the weakly linked
schedAppInit()function, which loads the example applications into the “Application Host”.
...
The system states used by the state machine are represented by the following constants, which have values in the set of negative integers, {x ε Z | x < 0}are all negative integers:
STATE_UNDEFINEDSTATE_ONCE(initialization)STATE_ACTIVATEDSTATE_DEACTIVATEDSTATE_SENDING_REQUESTSTATE_RECEIVING_RESPONSE
...
User-defined states are used to extend the Application Host system states for application specific purposes. These custom states are passed into the caller as a parameter to the polling callback function.
User-defined , application states MUST have values from the set of whole numbers, {x ε Z | x ≥ 0} be integers >= 0.
WARNING: Negative numbers are RESERVED for the system states and CANNOT be used for user-defined, application states.
...
NOTE: In order to interact with the Scheduler, you must know your application ID,
appID. This can and should be captured when you first register your application with the scheduler. However, theappIDis also provided as a form of context with each callback invocation.
schedAppConfig
| Code Block | ||
|---|---|---|
| ||
// App Configuration definition
typedef struct {
// General
const char *name;
// How often we get activated
uint32_t activationPeriodSecs;
// While app is active, how often it's polled
uint32_t pollIntervalSecs;
// Handlers
schedActivateFunc activateFn;
schedInterruptFunc interruptFn;
schedPollFunc pollFn;
schedResponseFunc responseFn;
// Application Context
void *appContext;
} schedAppConfig;
|
...
.activateFn-typedef bool (*schedActivateFunc) (int appID);Called on activation; you may return
falseto cancel any given activation.NOTEWARNING: that this This method must NOT send messages to the gateway; it's only allowed to do local operations are allowed.
.interruptFn-typedef void (*schedInterruptFunc) (int appID, uint16_t pins);A shared ISR that is called for ANY interrupt on ALL applications; the
pinsparameter indicatesextilines (https://wiki.st.com/stm32mcu/wiki/EXTI_feature_overview ) that changed. Due to the shared nature of the pin, you must filter to the pin you are expecting to handle in your application.Example: Filtering on the
PAIRbuttonCode Block language c if (!(pins & BUTTON1_Pin)) { return; }.pollFn-typedef void (*schedPollFunc) (int appID, int state);Called repeatedly while activated. This function implements the application's state machine, where negative states are reserved. Only when this function sends a message using the
noteSendToGatewayAsync()function, or manually submitsSTATE_DEACTIVATEto the scheduler, will the application will be deactivated..responseFn-typedef void (*schedResponseFunc) (int appID, J *rsp);Called after an application sent a Notecard request and is asynchronously receiving a reply. This will be called when a response comes back or when it times out; if timeout the
rspfield will beNULL.
...
static global variables (singleton model)
When application context is supplied as static global variables, then it is available to everything in the containing .c file. This is suitable for most single purpose applications (e.g. an interface to specific hardware, performs a unique operation, etc.). To use a static global variable, you only need to define a variable as static in the global space of your application’s .c file.appContext - portable struct (multiple instances)
However, there are several instances where a portable struct can facilitate code reuse and enable higher level abstractions (e.g. using one source file to interface to an array of identical sensors, enabling a context based language, etc.). To use a portable struct, you would define it in your application’s .c file, allocate it from the heap in an initialization function, and provide a pointer to the appContext field of the application configuration struct, schedAppConfig.
Console Logging
Console logging can be performed via the APP_PRINTF() function.
WARNING: The maximum number of characters is 90.
Dynamic Queue File Naming
...
*is a special character that will be replaced with the Sparrow node's ID by the Gateway.
Note Submission
Notes are submitted to the Gateway using the following API:
void noteSendToGatewayAsync(J *req, bool responseExpected)
The function has two parameters. The first is the JSON representation of the Note you would like to submit to the Notecard attached to the Sparrow Gateway. The second indicates whether or not a response is requested.
Invoking this API causes a cascade of changes to be made to the applications runtime.
The current state is send to
STATE_SENDING_REQUESTand if you indicated you were expecting a response, the state will change toSTATE_RECEIVING_RESPONSEafter sending the request.
However, both the success and failure states are set toSTATE_DEACTIVATED, which means whether your application succeeds or fails at it’s attempt to send the Note (or receive a response), it will ultimately become deactivated. If you wish to alter the success and failure states, thenschedSetCompletionState()can be called promptly afternoteSendToGatewayAsync()has returned.If a response has been requested, then the application will continue running - blocking the main thread of execution. This, in turn, prevents other applications from running.
Note Tracking
An If you have requested a response, then an arbitrary number can be added to the id tag of a the Note, which allows you to match it with a particular responsethe response with the original request. When "id" is supplied to a Note, then the response (which comes as the rsp parameter of diagResponse() callback) will contain a matching "id" tag
Console Logging
Console logging can be performed via the APP_PRINTF() function.
...
.
NOTE: Responses are expected to be used sparingly, as they work against the spirit of the typical LoRa communications model as well as the core of the Sparrow application design pattern. Responses can be an invaluable tool during the early development of a Sparrow application, but they should be removed (unless critical to the application) before an application is considered ready for production.
GPIO Special Interactions/Behaviors
Analog Pins
To enable the analog pins on the header rail (i.e. A1, A2, A3), the macro Ax_ENABLE where x corresponds to the desired analog pin (e.g. A1_ENABLE).
Digital Pins
RED- This pin is required to enable the evaluation of several internal variables and values. As such, this pin is in use by the system outside thepollFnrelated to your application. The implication is that this pin cannot be used as an interrupt or other function that would require it to operate in a continuous fashion.
Integrating a Custom Sensor into CMake
To add an application to the Sparrow firmware, you will be able to do everything from the sparrow-application folder by following these steps:
Create a new folder for your application in the
sparrow-applicationfolder.Create an application module (
.c/.hfiles) in your new folder.Multiple working examples exist, each in their own folder, listed under the
sparrow-applicationfolder.Update
sparrow-application/CMakeLists.txtto build your source file (.c) and include your header (.h)Each of the samples is also built by this
CMakeLists.txtfile.
Collecting Logs
Use an STLINK-V3MINI to connect to your device, you can use a terminal emulator to view the debugging output on the serial port that appears on your computer.
...
Pin # | Pin Name | Description | Pin # | Pin Name | Description | |
|---|---|---|---|---|---|---|
NRST | RST# | RESET Button | PA7 | MOSI | Main Out / Secondary In | |
PH3-BOOT0 | BOOT | BOOT Button | PA6 | MISO | Main In / Secondary Out | |
VSS_EP | GND | Ground | PA5 | SCK | SPI Clock | |
PA2 | LPTX | Low-Power UART Transmit | PA4 | CS | Chip Select | |
PA3 | LPRX | Low-Power UART Receive | PA11 | SDA | I2C Data | |
PB2 | A1 | Analog Pin 1 | PA12 | SCL | I2C Clock | |
PA10 | A2 | Analog Pin 2 | PA1 | BLUE | Blue LED | |
PA15 | A3 | Analog Pin 3 | PA0 | RED | Red LED | |
PA13 | SWDIO | Single-Wire Debug I/O | PB12 | GREEN | Green LED | |
PA14 | SWCLK | Single-Wire Debug Clock | PB6 | RX | UART Receive | |
PC13 | BTN# | PAIR Button | PB7 | TX | UART Transmit | |
VDD | <VIO | Logic-level Voltage | -- | VBAT | Direct Battery Voltage |
Link to Sparrow Schematic (PDF)
Link to Sparrow MCU Datasheet (PDF)
Additional Links
[DEPRECATED] v1.0 Hardware
Collecting Logs
...
FTDI
...
Pin Mapping
...
Sparrow FTDI Cable Color
...
GND
...
GND
...
BLACK
...
LPRX
...
TXD
...
ORANGE
...
LPTX
...
RXD
...
YELLOW
NOTE: The serial connection MUST be set to operate at 9600 (8-N-1).
Sparrow Rail Pinout
...
Pin #
...
Pin Name
...
Description
...
Pin #
...
Pin Name
...
Description
...
NRST
...
RST#
...
RESET Button
...
PA7
...
MOSI
...
Main Out / Secondary In
...
PH3-BOOT0
...
BOOT
...
BOOT Button
...
PA6
...
MISO
...
Main In / Secondary Out
...
VSS_EP
...
GND
...
Ground
...
PA5
...
SCK
...
SPI Clock
...
PB2
...
A1
...
Analog Pin 1
...
PA4
...
CS
...
Chip Select
...
PA10
...
A2
...
Analog Pin 2
...
PA2
...
LPTX
...
Low-Power UART Transmit
...
PA15
...
A3
...
Analog Pin 3
...
PA3
...
LPRX
...
Low-Power UART Receive
...
PA11
...
SDA
...
I2C Data
...
PA1
...
BLUE
...
Blue LED
...
PA12
...
SCL
...
I2C Clock
...
PA0
...
RED
...
Red LED
...
PA13
...
SWDIO
...
Single-Wire Debug I/O
...
PB12
...
GREEN
...
Green LED
...
PA14
...
SWCLK
...
Single-Wire Debug Clock
...
PB6
...
RX
...
UART Receive
...
PC13
...
BTN#
...
PAIR Button
...
PB7
...
TX
...
UART Transmit
...
VDD
...
<VIO
...
Logic-level Voltage
...
--
...
VBAT
...
Direct Battery Voltage
...