Skip to content

Commit 5e18c10

Browse files
author
oclyke
committed
update documentation
1 parent 2eca8f8 commit 5e18c10

File tree

52 files changed

+469
-484
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+469
-484
lines changed

Diff for: ‎LICENSE.md

-7
This file was deleted.

Diff for: ‎README.MD

+66
Original file line numberDiff line numberDiff line change
@@ -1 +1,67 @@
11
![Generate Variants Status Badge](https://github.com/sparkfun/Arduino_Apollo3/workflows/Generate%20Variants/badge.svg)
2+
3+
# SparkFun Ambiq Apollo3 Arduino Core
4+
An mbed-os enabled Arduino core for Ambiq Apollo3 based boards
5+
6+
## Contents
7+
- [SparkFun Ambiq Apollo3 Arduino Core](#sparkfun-ambiq-apollo3-arduino-core)
8+
- [Contents](#contents)
9+
- [Installation](#installation)
10+
- [**Arduino Boards Manager** (recommended)](#arduino-boards-manager-recommended)
11+
- [**Git** (development)](#git-development)
12+
- [Development Status](#development-status)
13+
- [Priorities](#priorities)
14+
- [More](#more)
15+
- [License](#license)
16+
- [Contributing](#contributing)
17+
- [Issue Template](#issue-template)
18+
- [Acknowledgements](#acknowledgements)
19+
20+
## Installation
21+
### **Arduino Boards Manager** (recommended)
22+
- Copy / paste the JSON package URL into the 'Additional Boards Manager URLs' field in Arduino preferences
23+
24+
[sparkfun/Arduino_Apollo3@master/package_sparkfun_apollo3.json (raw)](sparkfun/Arduino_Apollo3@master/package_sparkfun_apollo3.json)
25+
- Open 'Boards Manager' and select 'SparkFun Apollo3 Boards' - install the latest version
26+
27+
### **Git** (development)
28+
- Ensure the proper directory structure exists by following the [Arduino Boards Manager](#arduino-boards-manager) instructions (install latest)
29+
- Locate and enter the ```Arduino15``` directory
30+
- ```cd ~/.../Arduino15```
31+
- Run the ```dev-install.sh``` script
32+
- ```./packages/SparkFun/hardware/apollo3/*/tools/scripts/dev-install.sh```
33+
34+
## Development Status
35+
36+
- v2.0.0 based on an [mbed-os](https://github.com/ARMmbed/mbed-os) framework
37+
38+
#### Priorities
39+
- support additional capabilities using Apollo3 peripherals
40+
41+
**Main Arduino Features**
42+
* Serial: ✅
43+
* GPIO: ✅
44+
* Analog / Servo Output: ✅
45+
* Analog Input: ✅
46+
* Timing / Delays: ✅
47+
48+
**Standard Libraries**
49+
* Wire
50+
* Controller: ✅
51+
* Peripheral: ❌
52+
* SPI
53+
* Controller: ✅
54+
* Peripheral: ❌
55+
* Software Serial: ✅
56+
57+
**Apollo3 Specialty Peripherals**
58+
* PDM Microphones / I2S: ✅
59+
* BLE: ✅
60+
* Multi-bit SPI: 🤔
61+
* I2C/SPI Peripheral: 🤔
62+
63+
## More
64+
### [License](./docs/ISSUES.md)
65+
### [Contributing](./docs/CONTRIBUTING.md)
66+
### [Issue Template](./docs/ISSUES.md)
67+
### [Acknowledgements](./docs/ACKNOWLEDGEMENTS.md)

Diff for: ‎boards.txt

+2-19
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,5 @@
1-
# Copyright (c) 2020 SparkFun Electronics
2-
3-
# Permission is hereby granted, free of charge, to any person obtaining a copy
4-
# of this software and associated documentation files (the "Software"), to deal
5-
# in the Software without restriction, including without limitation the rights
6-
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7-
# copies of the Software, and to permit persons to whom the Software is
8-
# furnished to do so, subject to the following conditions:
9-
10-
# The above copyright notice and this permission notice shall be included in all
11-
# copies or substantial portions of the Software.
12-
13-
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14-
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15-
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16-
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17-
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18-
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19-
# SOFTWARE.
1+
# This file is subject to the terms and conditions defined in
2+
# file 'LICENSE.md', which is part of this source code package.
203

214
# Menu Options
225
menu.loader=Bootloader

Diff for: ‎cores/arduino/mbed-bridge

Diff for: ‎cores/arduino/sdk/ArduinoSDK.h

+3-20
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,6 @@
1-
/*
2-
Copyright (c) 2020 SparkFun Electronics
3-
4-
Permission is hereby granted, free of charge, to any person obtaining a copy
5-
of this software and associated documentation files (the "Software"), to deal
6-
in the Software without restriction, including without limitation the rights
7-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8-
copies of the Software, and to permit persons to whom the Software is
9-
furnished to do so, subject to the following conditions:
10-
11-
The above copyright notice and this permission notice shall be included in all
12-
copies or substantial portions of the Software.
13-
14-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20-
SOFTWARE.
1+
/*
2+
// This file is subject to the terms and conditions defined in
3+
// file 'LICENSE.md', which is part of this source code package.
214
*/
225

236
#ifndef _ARDUINO_SDK_ARDUINOSDK_H_

Diff for: ‎cores/arduino/sdk/core-extend/AnalogInternal.h

+3-20
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,6 @@
1-
/*
2-
Copyright (c) 2020 SparkFun Electronics
3-
4-
Permission is hereby granted, free of charge, to any person obtaining a copy
5-
of this software and associated documentation files (the "Software"), to deal
6-
in the Software without restriction, including without limitation the rights
7-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8-
copies of the Software, and to permit persons to whom the Software is
9-
furnished to do so, subject to the following conditions:
10-
11-
The above copyright notice and this permission notice shall be included in all
12-
copies or substantial portions of the Software.
13-
14-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20-
SOFTWARE.
1+
/*
2+
// This file is subject to the terms and conditions defined in
3+
// file 'LICENSE.md', which is part of this source code package.
214
*/
225

236
#ifndef _ARDUINO_SDK_CORE_EXTEND_ANALOG_INTERNAL_H_

Diff for: ‎cores/arduino/sdk/core-extend/Common.h

+3-20
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,6 @@
1-
/*
2-
Copyright (c) 2020 SparkFun Electronics
3-
4-
Permission is hereby granted, free of charge, to any person obtaining a copy
5-
of this software and associated documentation files (the "Software"), to deal
6-
in the Software without restriction, including without limitation the rights
7-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8-
copies of the Software, and to permit persons to whom the Software is
9-
furnished to do so, subject to the following conditions:
10-
11-
The above copyright notice and this permission notice shall be included in all
12-
copies or substantial portions of the Software.
13-
14-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20-
SOFTWARE.
1+
/*
2+
// This file is subject to the terms and conditions defined in
3+
// file 'LICENSE.md', which is part of this source code package.
214
*/
225

236
#ifndef _ARDUINO_SDK_CORE_EXTEND_COMMON_H_

Diff for: ‎cores/arduino/sdk/core-extend/ap3_types.h

+3-20
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,6 @@
1-
/*
2-
Copyright (c) 2020 SparkFun Electronics
3-
4-
Permission is hereby granted, free of charge, to any person obtaining a copy
5-
of this software and associated documentation files (the "Software"), to deal
6-
in the Software without restriction, including without limitation the rights
7-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8-
copies of the Software, and to permit persons to whom the Software is
9-
furnished to do so, subject to the following conditions:
10-
11-
The above copyright notice and this permission notice shall be included in all
12-
copies or substantial portions of the Software.
13-
14-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20-
SOFTWARE.
1+
/*
2+
// This file is subject to the terms and conditions defined in
3+
// file 'LICENSE.md', which is part of this source code package.
214
*/
225

236
// 'ap3_types.h' can be included in both C and C++ sources

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

+3-20
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,6 @@
1-
/*
2-
Copyright (c) 2020 SparkFun Electronics
3-
4-
Permission is hereby granted, free of charge, to any person obtaining a copy
5-
of this software and associated documentation files (the "Software"), to deal
6-
in the Software without restriction, including without limitation the rights
7-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8-
copies of the Software, and to permit persons to whom the Software is
9-
furnished to do so, subject to the following conditions:
10-
11-
The above copyright notice and this permission notice shall be included in all
12-
copies or substantial portions of the Software.
13-
14-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20-
SOFTWARE.
1+
/*
2+
// This file is subject to the terms and conditions defined in
3+
// file 'LICENSE.md', which is part of this source code package.
214
*/
225

236
#define PinMode Arduino_PinMode

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

+3-20
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,6 @@
1-
/*
2-
Copyright (c) 2020 SparkFun Electronics
3-
4-
Permission is hereby granted, free of charge, to any person obtaining a copy
5-
of this software and associated documentation files (the "Software"), to deal
6-
in the Software without restriction, including without limitation the rights
7-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8-
copies of the Software, and to permit persons to whom the Software is
9-
furnished to do so, subject to the following conditions:
10-
11-
The above copyright notice and this permission notice shall be included in all
12-
copies or substantial portions of the Software.
13-
14-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20-
SOFTWARE.
1+
/*
2+
// This file is subject to the terms and conditions defined in
3+
// file 'LICENSE.md', which is part of this source code package.
214
*/
225

236
#define PinMode Arduino_PinMode

Diff for: ‎docs/ACKNOWLEDGEMENTS.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Acknowledgements
2+
================================
3+
Contributors to the Apollo3 Arduino Core are listed here in last-name alphabetical order. More detailed information about contributions can be found using the git commit history of the project.
4+
5+
When submitting your first-accepted pull request add your name to this list properly alphebetized.
6+
7+
Thank you to everyone who has contributed!
8+
9+
Contributors
10+
============
11+
* Stephen Fordyce
12+
* Kenny Hora
13+
* Jim Lindblom
14+
* Owen Lyke
15+
* Aaron Micyus
16+
* Nathan Seidle

Diff for: ‎docs/CONTRIBUTING.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
What to Contribute
2+
==================
3+
Goals of this Arduino core, listed in order of priority, are:
4+
1. Coverage of the Arduino built-in functions demonstrated by Sketch compatibility.
5+
1. Creation of a well-structured and easy to extend Arduino core.
6+
1. Prioritizing usage of [mbed](https://github.com/ARMmbed/mbed-os) functionality
7+
1. Efficient use of existing AmbiqSuite HAL code.
8+
1. Backward-compatible improvements to the standard Arduino libraries.
9+
10+
Great things to contribute:
11+
- bug fixes
12+
- libaries to support Apollo3 peripherals
13+
14+
Where to Contribute
15+
===================
16+
In keeping with the goal of creating a well-structured, easy to understand, and easy to extend Arduino core it is importatnt to carefully consider where new code should be located.
17+
18+
There are two main places where you might add code:
19+
1. The core ```Arduino_Apollo3\cores\arduino```
20+
2. Variants ```Arduino_Apollo3\variants```
21+
22+
Code that goes in the core should be applicable to *any* Apollo3-based board as opposed to code that is specific to a particular variant.
23+
24+
How to Contribute
25+
=================
26+
27+
First, get an idea of whether or not your efforts will be worthwhile - you don't want to write a lot of code just to be told that the work doesn't fit the goals of the repo. There are two good places to discuss possible additions:
28+
29+
* [GitHub Issues](https://github.com/sparkfun/Arduino_Apollo3/issues): Follow the guidelines for submitting an issue ([Issue Template](./ISSUES.md)), then discussion of viability and best approach can ensue.
30+
* [SparkFun Apollo3 Arduino Core Development Forum](https://forum.sparkfun.com/viewforum.php?f=169&sid=dabc2a5f3fe0680ae8973aa9c324ebbd):
31+
32+
Consider where your contribution will fit best:
33+
- [Arduino-mbed bridge](https://github.com/sparkfun/arduino-mbed-bridge): for code that applies to **any** Arduino board based on mbed functionality
34+
- [SparkFun Ambiq Apollo3 mbed fork](https://github.com/sparkfun/mbed-os-ambiq-apollo3): for adding support for the Apollo3 microcontroller within mbed
35+
- [Arduino Apollo3](https://github.com/sparkfun/Arduino_Apollo3) (this repo): for support of Arduino functionality that is not covered in mbed
36+
37+
When you start to write code keep in mind the presentation of these changes. We accept changes using Github pull requests, as the most seamless way for both ourselves and contributors. When making commits for a change please use descriptive commit summaries. For considerable changes we expect a detailed yet formal and concise description of the change in the commit message. If you make 2 or more considerable changes, they should go in separate commits. The same applies to unrelated changes - for example, don't put formatting changes and actual code changes in one commit. Follow the [Code Conventions](https://github.com/sparkfun/Arduino_Apollo3/blob/master/docs/CODECONVENTIONS.md)
38+
39+
In your first accepted Pull Request it is up to you to add your name to the [Acknowledgements](https://github.com/sparkfun/Arduino_Apollo3/blob/master/docs/ACKNOWLEDGEMENTS.md) file. Please do this in its own individual commit. If you are contributing for a second, third, or nth time there is no need to add any more to the acknowledgements file - your contributions are recorded by your commit messages.
40+
41+
When you submit a pull request, please make sure that it's understood why you propose this change: what problem it addresses, how it improves the work and at the same time does not degrade it with respect to the priorities in the [What to Contribute](#what-to-contribute) section. Good, detailed commit messages are an easy way to achieve this, and yet sometimes it's better to put informal points, colloquial arguments and big examples in comments to a pull request instead, to keep commit messages concise and focused.

Diff for: ‎docs/ISSUES.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
### Subject of the issue
2+
Describe your issue here.
3+
4+
### Your workbench
5+
* What platform are you using?
6+
* What version of the device are you using? Is there a firmware version?
7+
* How is the device wired to your platform?
8+
* How is everything being powered?
9+
* Are there any additional details that may help us help you?
10+
11+
### Steps to reproduce
12+
Tell us how to reproduce this issue. Please post stripped down example code demonstrating your issue to a gist.
13+
14+
### Expected behaviour
15+
Tell us what should happen
16+
17+
### Actual behaviour
18+
Tell us what happens instead

0 commit comments

Comments
 (0)