Merge pull request #392 from sparkfun/release-candidate

v2.1.0

Author: Wenn0101

Diff for: README.MD

@@ -9,6 +9,7 @@ An mbed-os enabled Arduino core for Ambiq Apollo3 based boards
   - [Installation](#installation)
     - [**Arduino Boards Manager** (recommended)](#arduino-boards-manager-recommended)
     - [**Git** (development)](#git-development)
+  - [Getting Started](#getting-started)
   - [Development Status](#development-status)
       - [Priorities](#priorities)
   - [More](#more)
@@ -26,14 +27,33 @@ An mbed-os enabled Arduino core for Ambiq Apollo3 based boards
 
 ### **Git** (development)
   - Ensure the proper directory structure exists by following the [Arduino Boards Manager](#arduino-boards-manager) instructions (install latest)
-  - Locate and enter the ```Arduino15``` directory
-    - ```cd ~/.../Arduino15```
-  - Run the ```dev-install.sh``` script
-    - ```./packages/SparkFun/hardware/apollo3/*/tools/scripts/dev-install.sh```
+  - navigate to your directory with the latest version
+  - rename the directory from 2.x.x to .bckup2.x.x (or simply delete it and download it later if wanted)
+  - clone this repo
+  `git clone https://github.com/sparkfun/Arduino_Apollo3.git`
+  - checkout desired branch
+  `cd Arduino_Apollo3`
+  `git checkout release-candidate`
+  - update all submodules
+  `git submodule update --init --recursive`
+  - rename directory from Arduino_Apollo3 to 2.x.x from above
+  - restart Arduino and enjoy.
+
+## Getting Started
+For in depth tutorials, checkout out the [Artemis page](https://www.sparkfun.com/artemis) for the latest. Tutorials that may be of interest include:
+ - [Installing Board Definitions in the Arduino IDE](https://learn.sparkfun.com/tutorials/installing-board-definitions-in-the-arduino-ide)
+ - [Artemis Development with the Arduino IDE](https://learn.sparkfun.com/tutorials/artemis-development-with-the-arduino-ide)
+
+If you are comfortable with the arduino IDE and already have the boards installed, we recommend trying some examples from within the arduino IDE. Start with the "Built-in Examples" from arduino, but don't forget to checkout out some of the board specific examples that we have included with the package. These demonstrate how to use some of the libraries that make our Artemis board unique, and can take your next project to a new level!
 
 ## Development Status
 
-* v2.0.0 based on an [mbed-os](https://github.com/ARMmbed/mbed-os) framework
+* v2.0.0 Based on an [mbed-os](https://github.com/ARMmbed/mbed-os) framework
+* v2.1.0 Contains latest fixes for the v2 core and feature that have been added since v2 release
+
+For more information on how to contribute or how to navigate this repo, check out the [Contributing](./docs/CONTRIBUTING.md) page.
+
+As mentioned MbedOS is the framework to our latest Arduino Core. To contribute to, or use these targets on, MbedOS check out the [main repo by ARM](https://github.com/ARMmbed/mbed-os). This library uses mbed libraries built from a fork of mbed that is maintained by us. The latest version of that repo can be found [here](https://github.com/sparkfun/mbed-os-ambiq-apollo3/tree/ambiq-apollo3-arduino).
 
 **Main Arduino Features**
   * Serial: ✅
@@ -56,11 +76,11 @@ An mbed-os enabled Arduino core for Ambiq Apollo3 based boards
   * PDM Microphones / I2S: ✅
   * BLE: ✅
   * RTC: ✅
-  * Watchdog Timer: 🤔
-  * Multi-bit SPI: 🤔
+  * Watchdog Timer: ✅
+  * Burst Mode: ✅
 
 ## More
-### [License](./docs/ISSUES.md)
+### [License](./docs/LICENSE.md)
 ### [Contributing](./docs/CONTRIBUTING.md)
 ### [Issue Template](./docs/ISSUES.md)
 ### [Acknowledgements](./docs/ACKNOWLEDGEMENTS.md)

Diff for: boards.txt

@@ -36,11 +36,11 @@ sfe_artemis.build.defines=
 sfe_artemis.build.includes=
 sfe_artemis.build.libs=
 
-sfe_artemis.menu.svl_baud.921600=921600
 sfe_artemis.menu.svl_baud.460800=460800
 sfe_artemis.menu.svl_baud.230400=230400
 sfe_artemis.menu.svl_baud.115200=115200
 sfe_artemis.menu.svl_baud.57600=57600
+sfe_artemis.menu.svl_baud.921600=921600
 sfe_artemis.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 sfe_artemis.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 
@@ -72,11 +72,11 @@ sfe_artemis_atp.build.defines=
 sfe_artemis_atp.build.includes=
 sfe_artemis_atp.build.libs=
 
-sfe_artemis_atp.menu.svl_baud.921600=921600
 sfe_artemis_atp.menu.svl_baud.460800=460800
 sfe_artemis_atp.menu.svl_baud.230400=230400
 sfe_artemis_atp.menu.svl_baud.115200=115200
 sfe_artemis_atp.menu.svl_baud.57600=57600
+sfe_artemis_atp.menu.svl_baud.921600=921600
 sfe_artemis_atp.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 sfe_artemis_atp.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 
@@ -108,11 +108,11 @@ sfe_artemis_nano.build.defines=
 sfe_artemis_nano.build.includes=
 sfe_artemis_nano.build.libs=
 
-sfe_artemis_nano.menu.svl_baud.921600=921600
 sfe_artemis_nano.menu.svl_baud.460800=460800
 sfe_artemis_nano.menu.svl_baud.230400=230400
 sfe_artemis_nano.menu.svl_baud.115200=115200
 sfe_artemis_nano.menu.svl_baud.57600=57600
+sfe_artemis_nano.menu.svl_baud.921600=921600
 sfe_artemis_nano.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 sfe_artemis_nano.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 
@@ -144,11 +144,11 @@ sfe_artemis_thing_plus.build.defines=
 sfe_artemis_thing_plus.build.includes=
 sfe_artemis_thing_plus.build.libs=
 
-sfe_artemis_thing_plus.menu.svl_baud.921600=921600
 sfe_artemis_thing_plus.menu.svl_baud.460800=460800
 sfe_artemis_thing_plus.menu.svl_baud.230400=230400
 sfe_artemis_thing_plus.menu.svl_baud.115200=115200
 sfe_artemis_thing_plus.menu.svl_baud.57600=57600
+sfe_artemis_thing_plus.menu.svl_baud.921600=921600
 sfe_artemis_thing_plus.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 sfe_artemis_thing_plus.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 
@@ -180,12 +180,12 @@ sfe_edge.build.defines=
 sfe_edge.build.includes=
 sfe_edge.build.libs=
 
-sfe_edge.menu.svl_baud.921600=921600
+
 sfe_edge.menu.svl_baud.460800=460800
 sfe_edge.menu.svl_baud.230400=230400
 sfe_edge.menu.svl_baud.115200=115200
 sfe_edge.menu.svl_baud.57600=57600
-
+sfe_edge.menu.svl_baud.921600=921600
 sfe_edge.menu.asb_baud.921600=921600 (SparkFun.com)
 sfe_edge.menu.asb_baud.115200=115200 (TensorFlow Conference)
 
@@ -221,11 +221,11 @@ sfe_edge2.build.defines=
 sfe_edge2.build.includes=
 sfe_edge2.build.libs=
 
-sfe_edge2.menu.svl_baud.921600=921600
 sfe_edge2.menu.svl_baud.460800=460800
 sfe_edge2.menu.svl_baud.230400=230400
 sfe_edge2.menu.svl_baud.115200=115200
 sfe_edge2.menu.svl_baud.57600=57600
+sfe_edge2.menu.svl_baud.921600=921600
 sfe_edge2.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 sfe_edge2.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 
@@ -257,11 +257,11 @@ sfe_artemis_mm_pb.build.defines=
 sfe_artemis_mm_pb.build.includes=
 sfe_artemis_mm_pb.build.libs=
 
-sfe_artemis_mm_pb.menu.svl_baud.921600=921600
 sfe_artemis_mm_pb.menu.svl_baud.460800=460800
 sfe_artemis_mm_pb.menu.svl_baud.230400=230400
 sfe_artemis_mm_pb.menu.svl_baud.115200=115200
 sfe_artemis_mm_pb.menu.svl_baud.57600=57600
+sfe_artemis_mm_pb.menu.svl_baud.921600=921600
 sfe_artemis_mm_pb.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 sfe_artemis_mm_pb.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 
@@ -293,11 +293,11 @@ sfe_artemis_module.build.defines=
 sfe_artemis_module.build.includes=
 sfe_artemis_module.build.libs=
 
-sfe_artemis_module.menu.svl_baud.921600=921600
 sfe_artemis_module.menu.svl_baud.460800=460800
 sfe_artemis_module.menu.svl_baud.230400=230400
 sfe_artemis_module.menu.svl_baud.115200=115200
 sfe_artemis_module.menu.svl_baud.57600=57600
+sfe_artemis_module.menu.svl_baud.921600=921600
 sfe_artemis_module.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 sfe_artemis_module.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 
@@ -337,11 +337,11 @@ lora_thing_plus.build.defs=
 lora_thing_plus.build.libs=
 
 
-lora_thing_plus.menu.svl_baud.921600=921600
 lora_thing_plus.menu.svl_baud.460800=460800
 lora_thing_plus.menu.svl_baud.230400=230400
 lora_thing_plus.menu.svl_baud.115200=115200
 lora_thing_plus.menu.svl_baud.57600=57600
+lora_thing_plus.menu.svl_baud.921600=921600
 lora_thing_plus.menu.loader.option_svl=SparkFun Variable Loader (Recommended)
 lora_thing_plus.menu.loader.option_asb=Ambiq Secure Bootloader (Advanced)
 

Diff for: cores/arduino/sdk/core-implement/CommonAnalog.cpp

@@ -213,10 +213,11 @@ ap3_err_t analogWriteFrameWidth(uint32_t width){
 
 ap3_err_t analogWriteFrequency(float freq){    
     uint32_t new_width = (uint32_t)(AP3_ANALOG_CLK_FREQ / freq);
+
     if (new_width > AP3_MAX_ANALOG_WRITE_WIDTH){
         return AP3_ERR;
     }
-    if (new_width < AP3_MAX_ANALOG_WRITE_WIDTH){
+    if (new_width < AP3_MIN_ANALOG_WRITE_WIDTH){
         return AP3_ERR;
     }
     _analogWriteWidth = new_width;

Diff for: cores/mbed-os

@@ -0,0 +1,42 @@
+//Burst Mode example
+//TEST_PIN is toggled as fast as possible, with burst mode enable and disabled.
+//Use a logic analyzer to view the difference in output
+#include "BurstMode.h"
+
+#define TEST_PIN D2 //Change to whatever pin you would like
+
+#define NUM_TOGGLES 20 //Number of times to toggle the gpio as an example task
+
+void setup() {
+  Serial.begin(115200); 
+  Serial.println("BurstMode Example1 - Enable and Disable");
+}
+
+void loop() {
+  long startTime, endTime;
+  enableBurstMode(); //Go to 96MHz
+  //Toggle the with digital write as fast as possible, 20 times
+  startTime = micros();
+  for(int i = 0; i < NUM_TOGGLES; i++)
+  {
+    digitalWrite(TEST_PIN, HIGH);
+    digitalWrite(TEST_PIN, LOW);
+  }
+  endTime = micros();
+  Serial.printf("Time (in microseconds) to toggle GPIO %d times = %d, at clock speed %d \r\n",
+                                              NUM_TOGGLES, (endTime - startTime), getCpuFreqMHz());
+
+  disableBurstMode(); //Go back to 48MHz
+  //Toggle the with digital write as fast as possible, 20 times
+  startTime = micros();
+  for(int i = 0; i < NUM_TOGGLES; i++)
+  {
+    digitalWrite(TEST_PIN, HIGH);
+    digitalWrite(TEST_PIN, LOW);
+  }
+  endTime = micros();
+  Serial.printf("Time (in microseconds) to toggle GPIO %d times = %d, at clock speed %d \r\n",
+                                              NUM_TOGGLES, (endTime - startTime), getCpuFreqMHz());
+  
+  delay(1000);
+}

Diff for: libraries/BurstMode/examples/Example1_EnableDisable/Example1_EnableDisable.ino

@@ -0,0 +1,16 @@
+# Syntax Coloring Map For 'libraries/BurstMode'
+
+# Datatypes (KEYWORD1)
+
+
+# Functions (KEYWORD2)
+enableBurstMode KEYWORD2
+disableBurstMode KEYWORD2
+getCpuFreqMHz KEYWORD2
+
+# Structures (KEYWORD3)
+
+# Constants (LITERAL1)
+
+# Properties (LITERAL2)
+

Diff for: libraries/BurstMode/keywords.txt

@@ -0,0 +1,9 @@
+name=BurstMode
+version=2.0.0
+author=SparkFun Electronics
+maintainer=SparkFun Electronics <sparkfun.com>
+sentence=Burst Mode library for the SparkFun Artemis
+paragraph=Allows for enabling, disabling, and checking status of burst mode which changes the clock from 48Mhz to 96Mhz
+category=
+url=
+architectures=apollo3

Diff for: libraries/BurstMode/library.properties

@@ -0,0 +1,50 @@
+#include "BurstMode.h"
+
+uint32_t cpuFreq = 48000000; //At POR core is 48MHz
+
+//Turns main processor from 48MHz to 96MHz
+//Returns false if burst mode failed to enable
+bool enableBurstMode(void)
+{
+    // Check that the Burst Feature is available.
+    am_hal_burst_avail_e eBurstModeAvailable;
+    if (AM_HAL_STATUS_SUCCESS != am_hal_burst_mode_initialize(&eBurstModeAvailable))
+    {
+        return (false);
+    }
+
+    // Put the MCU into "Burst" mode.
+    am_hal_burst_mode_e eBurstMode;
+    if (AM_HAL_STATUS_SUCCESS != am_hal_burst_mode_enable(&eBurstMode))
+    {
+        return (false);
+    }
+    cpuFreq = 96000000;
+    return (true);
+}
+
+//Turns main processor from 96MHz to 48MHz
+//Returns false if disable fails
+bool disableBurstMode(void)
+{
+    am_hal_burst_mode_e eBurstMode;
+    if (AM_HAL_STATUS_SUCCESS == am_hal_burst_mode_disable(&eBurstMode))
+    {
+        if (AM_HAL_NORMAL_MODE != eBurstMode)
+        {
+            return (false);
+        }
+    }
+    else
+    {
+        return (false);
+    }
+    cpuFreq = 48000000;
+    return (true);
+}
+
+//Returns the current core speed
+uint32_t getCpuFreqMHz(void)
+{
+    return (cpuFreq);
+}

Diff for: libraries/BurstMode/src/BurstMode.cpp

@@ -0,0 +1,31 @@
+/*
+Copyright (c) 2019 SparkFun Electronics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+#ifndef _AP3_CLOCK_SOURCES_H_
+#define _AP3_CLOCK_SOURCES_H_
+
+#include "Arduino.h"
+
+bool enableBurstMode();
+bool disableBurstMode();
+uint32_t getCpuFreqMHz();
+
+#endif //_AP3_GPIO_H_

Diff for: libraries/BurstMode/src/BurstMode.h

@@ -13,6 +13,7 @@
 void setup() {
   SERIAL.begin(115200);
   SERIAL.println("EEPROM Example1_PutGet");
+  EEPROM.init();
 
   // use EEPROM.get(int index, T type) to retrieve
   // an arbitrary type from flash memory

Diff for: libraries/EEPROM/examples/Example1_PutGet/Example1_PutGet.ino

@@ -36,8 +36,8 @@ void setup()
 
   // The variant files for Artemis carrier boards have Mic data and clock pins defined
   // but these pins can be passed to the the .begin function
-  //if (myPDM.begin() == false) //Use Data, clock defines from variant file
-  if (myPDM.begin(22, 23) == false) //Data, clock on Artemis Nano - These are the pin names from variant file, not pad names
+  if (myPDM.begin() == false) //Use Data, clock defines from variant file
+  //if (myPDM.begin(22, 23) == false) //Data, clock on Artemis Nano - These are the pin names from variant file, not pad names
   {
     Serial.println("PDM Init failed. Are you sure these pins are PDM capable?");
     while (1)