Skip to content

Commit 77de1ad

Browse files
gigapodgigapod
authored
Merge pull request #178 from sparkfun/develop
cleaned up documentation a bit - prep for release
2 parents 424cfab + 355b23f commit 77de1ad

File tree

2 files changed

+134
-92
lines changed

2 files changed

+134
-92
lines changed

‎README.md

+22-9
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,33 @@
11

22
# SparkFun flux-sdk
33

4-
SDK and Framework to simplify the development of embedded applications
4+
The SparkFun flux-sdk is an embedded framework focused on the rapid development of fully featured embedded applications. Build around the concept of adding high-level "capabilities" to an application with minimal development effort, the sdk provides a wide-variety of high-level objects that automatically fit together to form a cohesive and rapidly developed application.
5+
6+
Key functionality provided by the framework:
7+
8+
* Automatic I2C (qwiic) device discovery, initialization and use.
9+
* Automatic serial driven menu configuration system based on the application definition
10+
* Automatic system persistance - local and SD card file
11+
* Multi-format Data logging support - serial and SD card files
12+
* Support for a wide range of IoT device services (AWS IoT, Azure IoT, Arduino IoT, Thingspeak, MQTT,..)
13+
* Extensive I2C (qwiic) device support
14+
* Easy to extend and customize development
15+
16+
For further details, a detailed documentation for flux is provided [here](https://docs.sparkfun.com/flux-sdk/)
517

618
## Status
719

8-
## Using Flux SDK
20+
### November 2024
921

10-
The flux-sdk is a development framework/SDK intended for use as a component within other Firmware applications. As such, it's incorporated into other projects as an Arduino library.
22+
The flux-sdk was developed as an internal tool initially, but is now being made public. The current functionality is a key component of several SparkFun products and relatively stable, but the sdk supporting functionality (documentation and examples) are in an **alpha** form at best.
1123

12-
To build firmware using Flux, see [Building with Flux](docs/build_with_flux.md)
24+
Over the next several quarters improvements to the sdk include:
1325

14-
## Framework Development
26+
* Improved documentation on using the sdk, as well as adding functionality to it (device drivers for example)
27+
* Remove any out of date remnants from the original version of the sdk - "spark" (which was started in 2020).
28+
* Add support for additional platforms. Currently the focus is ESP32, but a Raspberry Pi RP2350 solution is being developed
29+
* Add additional devices as needed.
1530

16-
Adding new capabilities to the Flux Framework
31+
## Documentation
1732

18-
* Implementing a [Device Class](docs/device_writing.md)
19-
* Implementing [Properties](docs/properties.md)
20-
* Implementing [Parameters](docs/parameters.md)
33+
As noted above, the current documentation for the flux-sdk is located [here](https://docs.sparkfun.com/flux-sdk/)

‎docs/build_with_flux.md

+112-83
Original file line numberDiff line numberDiff line change
@@ -3,145 +3,174 @@
33

44
This section outline the steps needed to support Flux in an Arduino Build Environment. Both support for Arduino IDE development, as well as automated builds that use the Arduino CLI (GitHub actions).
55

6-
Since Flux is private, only available to SparkFun employees and approved partners, the build integration is different from standard Open Source projects.
6+
Unlike standard Arduino Libraries, the flux-sdk uses the `cmake` build system to create a custom Arduino Library for the target application. This allows the specification of a target platform ias well as the specific features and functionality used in the target application.
77

8-
## Using Flux within the Arduino IDE
8+
The cmake build system creates the target Arduino Library, the library is either located in builds systems Arduino library directory (normally in the users Documentation/Arduino/libraries folder) or specified using the ```--library``` option to the ```arduino-cli``` tool.
99

10-
While Flux is structured as an Arduino library, being private, it's not available in the Arduino Library Manager. To use Flux within the Arduino IDE, it is manually installed in the Arduino libraries directory.
10+
## Building an Application Specific flux-sdk Library
1111

12-
Flux is installed by cloning the SparkFun_Flux GitHub repository. To do this, open a terminal on the desired development machine, and change the current directory to your Arduino Libraries install directory. This is normally ```HOME_DIRECTORY/Documents/Arduino/libraries```
12+
A custom library is configured and built using the standard build tool `cmake`
1313

14-
From this location, use the following git command to download and install the ***SparkFun_Flux*** library.
14+
### Install the *flux sdk*
15+
16+
The flux sdk is used to create a custom Arduino Library called ```SparkFun_Flux``` that is made available for use by the Arduino build environment. This allows tailoring which components are needed for the specific application - in this case the datalogger.
17+
18+
First steps is to download the flux-sdk on your machine - which is cloned from github.
1519

1620
```sh
17-
git clone [email protected]:sparkfun/SparkFun_Flux.git
21+
git clone [email protected]:sparkfun/flux-sdk.git
1822
```
1923

20-
Take note, security keys/access to the Flux Private library is required for the clone command to complete successfully.
24+
The normal location is to set install the flux-sdk in the same directory as the ```sfe-dataloger``` (this) repository was installed. If you install it some other location, set the flux-sdk path using the FLUX_SDK_PATH environment variable. This is easily done by cd'ing into the flux-sdk root directory and executing the following command:
2125

22-
Once installed, the SparkFun_Flux library is available to other applications/sketches within the Arduino Environment and used like any other Arduino library.
26+
```sh
27+
export FLUX_SDK_PATH=`pwd`
28+
```
2329

24-
Once you installed Flux locally, you can rapidly install the Arduino library dependencies for Flux using the ```arduino-cli``` as highlighted [later on this page](#install-flux-dependencies).
30+
### Configure cmake
2531

26-
## Using Flux within a Server/Batch Build Process
32+
To specify what components of flux are used by a project, a ```CMakeLists.txt``` file is used. This file is placed in the root of your project folder and outlines what modules of the flux-sdk to use make available.
2733

28-
To use Flux in another project that is being build using build automation (GitHub Actions), Flux should be added as a git submodule to the project, normally in the root directory of the projects repository. The following command is used:
34+
The following is an example of a cmake file from the SparkFun DataLogger IoT application:
35+
36+
```cmake
37+
38+
cmake_minimum_required(VERSION 3.13)
39+
40+
# set project name - setting language to NONE disables the default compiler checks
41+
project(DataLoggerIoT NONE)
42+
43+
# Import the flux-dk cmake system
44+
include(flux_sdk_import.cmake)
45+
46+
# Where is directory that the flux stuff will be added to? This is the relative path from this file
47+
# to the arduino sketch directory this is also used as the name of the cmake project
48+
flux_sdk_set_project_directory(.)
49+
50+
# datalogger is esp32 based
51+
flux_sdk_set_platform(platform_esp32)
52+
53+
# Currently we are using all modules of the SDK
54+
flux_sdk_add_module(flux_all_modules)
55+
56+
# now call the init function/macro - this will build the Arduino Library SparkFun_Flux under this
57+
# main directory
58+
flux_sdk_init()
2959
30-
```sh
31-
git submodule add [email protected]:sparkfun/SparkFun_Flux.git
3260
```
3361

34-
With this structure in place, access to the Flux within a GitHub action is accomplished by using ssh keys.
62+
The key components of this file are the following include the standard cmake version check, and then setting the project name using this line:
3563

36-
The first step is to generate a new key locally - in a shell
64+
```cmake
65+
# set project name - setting language to NONE disables the default compiler checks
66+
project(DataLoggerIoT NONE)
67+
```
3768

38-
```sh
39-
ssh-keygen -t rsa -b 4096 -C "Access to flux"
69+
After the project is defined, the cmake flux-sdk functions and configuration routines are included as follows:
70+
71+
```cmake
72+
# Import the flux-dk cmake system
73+
include(flux_sdk_import.cmake)
4074
```
4175

42-
For this command, don't add a password and you can save the key to a temporary place.
76+
The file `flux_sdk_import.cmake` is located in `external` folder of the flux-sdk ($FLUX_SDK/external) and should be copied to the same folder that contains your projects CMakeLists.txt file.
4377

44-
Next add the public part of the key to the Flux repo as a deploy key. In the Flux github repository, open the page: ```Settings > Deploy Keys``` and click the ***Add deploy key*** button on the page.
78+
The next line sets the location of the project. In this example, it's just the current working directory.
4579

46-
![Add Deploy Key](images/github_deploy_keys.png)
80+
```cmake
81+
# Where is directory that the flux stuff will be added to? This is the relative path from this file
82+
# to the arduino sketch directory this is also used as the name of the cmake project
83+
flux_sdk_set_project_directory(.)
84+
```
4785

48-
Give the key a descriptive name (***my project access key***) and paste the public part of the key into the dialog. Keep the key read-only.
86+
The platform used for the build is set using the following line (note, currently the flux-sdk is only supported on ESP32):
4987

50-
The next step is to add the private part of the key as a ***secret*** in main project (the project using flux) github repository. This is done in ```Settings > Secrets and variables > Actions``` page. On this page, on the **Secrets** tab, select the ***New repository secret*** button.
88+
```cmake
89+
# datalogger is esp32 based
90+
flux_sdk_set_platform(platform_esp32)
91+
```
5192

52-
![Action Secret](images/github_action_secret.png)
93+
The flux-sdk components or `modules` that are included in the application are specified using the `flux_sdk_add_module()` call. The modules correspond to folder names within the `src` folder of the sdk - for example to add the BME280 sensor device, the module name is `device_bme280`.
5394

54-
In the provided dialog, enter a name for the secret (follow variable naming methodology) and set the value to the private portion of the generated key.
95+
To add everything, the name `flux_all_modules` is used, and shown in the example above.
5596

56-
## Download the Flux Submodule
97+
```cmake
98+
# Currently we are using all modules of the SDK
99+
flux_sdk_add_module(flux_all_modules)
100+
```
57101

58-
Within a github action, the key is used to download the Flux submodule. Once the main repository is checked out, the Flux submodule is checked out with the following action code:
102+
The last step in the cmake file is calling the sdk init function `flux_sdk_init()`.
59103

60-
```yaml
61-
# setup the ssh key used to pull in the Flux submodule source. This was the
62-
# only way found to make this work when using private models (ssh private key here, public on Flux deploy keys
63-
- name: Download Flux Submodule
64-
uses: webfactory/ssh-agent@master
65-
with:
66-
ssh-private-key: |
67-
${{ secrets.FLUX_PULL_KEY_2 }}
68-
69-
# checkout flux
70-
- name: Checkout Flux submodule
71-
run: git submodule update --init --recursive
104+
```cmake
105+
# now call the init function/macro - this will build the Arduino Library SparkFun_Flux under this
106+
# main directory
107+
flux_sdk_init()
72108
```
73109

74-
NOTE: In this example, ```FLUX_PULL_KEY_2``` is the name of the Flux key secret within this repository.
110+
### Building the custom Flux Arduino Library
75111

76-
Once the Flux submodule is checked out, the application is setup and built using the Arduino Command Line (```arduino-cli```)
112+
configure the library used during the Arduino build process, the ```cmake``` system is used. The following steps outline how the custom library is built.
77113

78-
## Using Arduino CLI
114+
Set the current directory the root of your project. Then create a directory called build and cd into it.
115+
116+
```sh
117+
mkdir build
118+
cd build
119+
```
79120

80-
### Installation
121+
Now run CMake with the following command:
81122

82-
The Arduino CLI installation is outlined on this [page](https://arduino.github.io/arduino-cli/0.20/installation/).
123+
```sh
124+
cmake ..
125+
```
83126

84-
If working within a github action, the following code will install and setup the arduino-cli:
127+
This will create an Arduino library called ```SparkFun_Flux``` in the root directory of the project. Once completed, you can delete the build directory, and build the projects firmware.
85128

86-
```yaml
87-
# Setup Arduino command line - install esp32 and all the libs flux needs
88-
- name: Arduino - Install and setup the Arduino CLI
89-
uses: arduino/setup-arduino-cli@v1
129+
This custom library can be copied to the Arduino libraries install folder and used like a standard Arduino library, or referenced using the ```---library``` flag of the arduion-cli command
90130

91-
- name: Arduino - Start config file
92-
run: arduino-cli config init --additional-urls "https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json"
131+
## Building using the Arduino CLI
93132

94-
- name: Arduino - Update index
95-
run: arduino-cli core update-index
133+
### Install Arduino CLI
96134

97-
# Install ESP32
98-
- name: Arduino - Install ESP32 platform
99-
run: arduino-cli core install esp32:esp32
100-
```
135+
First, install the ```arduino-cli``` on your system. Details on how to do this are located [here](https://arduino.github.io/arduino-cli/0.20/installation/). While the arduino-cli isn't required to configure or build a flux build Arduino library, it helps with configuration.
101136

102-
Note: The above example also installed the ESP32 platform
137+
#### Install the Target Arduino Core
103138

104-
### Install Flux Dependencies
139+
Once the CLI is installed, the target core for the application can be installed using the arduino-cli. Note: this can also be performed within the Arduino application itself.
105140

106-
The Flux repository includes a script that installs all library dependencies using the ```arduino-cli```. This command, ```install-libs.sh``` is located within the root directory of the Flux repository.
141+
For example,the following commands complete the installation and install the ESP32 Arduino platform
107142

108-
To run this command within a github Action, the following code is used:
143+
```sh
144+
arduino-cli config init --additional-urls "https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json"
145+
146+
arduino-cli core update-index
109147

110-
```yaml
111-
# install the libraries Flux uses
112-
- name: Install Flux dependant libraries.
113-
run: ./SparkFun_Flux/install-libs.sh
148+
arduino-cli core install esp32:esp32
114149
```
115150

116-
Note: The above command assumes Flux is installed in the root directory of the repository. Adjust the command path to the structure of your repository if needed.
151+
### Install dependant Arduino libraries
152+
153+
Once the flux-sdk is installed, you can install all libraries the framework depends on by issuing the following command (note this command uses the ```arduino-cli```):
154+
155+
```sh
156+
$FLUX_SDK_PATH/install-libs.sh
157+
```
117158

118159
### Compile and Build
119160

120161
Once all the dependencies are installed, the ```arduino-cli compile``` option is called to build the desired application. To use Flux as a library, the ```--library``` switch is used with the compile call.
121162

122-
The following is an example of building an ESP32 based sketch, which uses the Flux library.
163+
The following is an example of building an ESP32 based sketch (the SparkFun DataLogger Application), which uses the custom Flux library.
123164

124165
Note that the location of the Flux library is passed in using the ```--library'`` switch, and that the ***full*** path to the Flux directory is provided. Using a relative path to the Flux library directory causes this command to fail
125166

126-
```yaml
127-
- name: Compile DataLogger firmware binary
128-
run: arduino-cli compile --fqbn esp32:esp32:esp32
129-
./sfeDataLoggerIoT/sfeDataLoggerIoT.ino
167+
```sh
168+
arduino-cli compile --fqbn esp32:esp32:esp32 ./sfeDataLoggerIoT/sfeDataLoggerIoT.ino \
130169
--export-binaries --library `pwd`/SparkFun_Flux
131170
```
132171

133-
### After the Build
172+
Once the build is complete, the resultant binary files are located in: `sfeDataLoggerIoT/build/esp32.esp32.esp32/`
134173

135-
For reference, once the above compile command is completed, the resultant Firmware binary is renamed and uploaded as an Action artifact using the following code:
174+
## Further Details
136175

137-
```yaml
138-
- name: Rename Library
139-
run: |
140-
cd sfeDataLoggerIoT/build/esp32.esp32.esp32/
141-
mv sfeDataLoggerIoT.ino.bin SparkFun_DataLoggerIoT.bin
142-
143-
- uses: actions/upload-artifact@v3
144-
with:
145-
name: SparkFun_DataLoggerIoT.bin
146-
path: sfeDataLoggerIoT/build/esp32.esp32.esp32/SparkFun_DataLoggerIoT.bin
147-
```
176+
A great example of how to build a flux-sdk application at the command line, as well as part of a github action is the SparkFun DataLogger IoT application, located [here](https://github.com/sparkfun/sfe-datalogger)

0 commit comments

Comments
 (0)