Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • card10/firmware
  • annejan/firmware
  • astro/firmware
  • fpletz/firmware
  • gerd/firmware
  • fleur/firmware
  • swym/firmware
  • l/firmware
  • uberardy/firmware
  • wink/firmware
  • madonius/firmware
  • mot/firmware
  • filid/firmware
  • q3k/firmware
  • hauke/firmware
  • Woazboat/firmware
  • pink/firmware
  • mossmann/firmware
  • omniskop/firmware
  • zenox/firmware
  • trilader/firmware
  • Danukeru/firmware
  • shoragan/firmware
  • zlatko/firmware
  • sistason/firmware
  • datenwolf/firmware
  • bene/firmware
  • amedee/firmware
  • martinling/firmware
  • griffon/firmware
  • chris007/firmware
  • adisbladis/firmware
  • dbrgn/firmware
  • jelly/firmware
  • rnestler/firmware
  • mh/firmware
  • ln/firmware
  • penguineer/firmware
  • monkeydom/firmware
  • jens/firmware
  • jnaulty/firmware
  • jeffmakes/firmware
  • marekventur/firmware
  • pete/firmware
  • h2obrain/firmware
  • DooMMasteR/firmware
  • jackie/firmware
  • prof_r/firmware
  • Draradech/firmware
  • Kartoffel/firmware
  • hinerk/firmware
  • abbradar/firmware
  • JustTB/firmware
  • LuKaRo/firmware
  • iggy/firmware
  • ente/firmware
  • flgr/firmware
  • Lorphos/firmware
  • matejo/firmware
  • ceddral7/firmware
  • danb/firmware
  • joshi/firmware
  • melle/firmware
  • fitch/firmware
  • deurknop/firmware
  • sargon/firmware
  • markus/firmware
  • kloenk/firmware
  • lucaswerkmeister/firmware
  • derf/firmware
  • meh/firmware
  • dx/card10-firmware
  • torben/firmware
  • yuvadm/firmware
  • AndyBS/firmware
  • klausdieter1/firmware
  • katzenparadoxon/firmware
  • xiretza/firmware
  • ole/firmware
  • techy/firmware
  • thor77/firmware
  • TilCreator/firmware
  • fuchsi/firmware
  • dos/firmware
  • yrlf/firmware
  • PetePriority/firmware
  • SuperVirus/firmware
  • sur5r/firmware
  • tazz/firmware
  • Alienmaster/firmware
  • flo_h/firmware
  • baldo/firmware
  • mmu_man/firmware
  • Foaly/firmware
  • sodoku/firmware
  • Guinness/firmware
  • ssp/firmware
  • led02/firmware
  • Stormwind/firmware
  • arist/firmware
  • coon/firmware
  • mdik/firmware
  • pippin/firmware
  • royrobotiks/firmware
  • zigot83/firmware
  • mo_k/firmware
106 results
Show changes
Commits on Source (1773)
Showing
with 2064 additions and 17 deletions
flags = -DBOARD_CARD10=1 -D_FILE_OFFSET_BITS=64 -DTARGET=32665 -DTARGET_REV=0x4131 -Ibuild/../hw-tests/api-demo -Ibuild/hw-tests/api-demo/ -Ibuild/hw-tests/api-demo/53736c5@@api-demo-core0.elf@exe -Ibuild/hw-tests/api-demo/53736c5@@api-demo-core1.elf@exe -Ibuild/../hw-tests/bmatest -Ibuild/hw-tests/bmatest/ -Ibuild/hw-tests/bmatest/9cb7b92@@bmatest.elf@exe -Ibuild/../hw-tests/bmetest -Ibuild/hw-tests/bmetest/ -Ibuild/hw-tests/bmetest/6886391@@bmetest.elf@exe -Ibuild/../hw-tests/dual-core -Ibuild/hw-tests/dual-core/ -Ibuild/hw-tests/dual-core/b5198ad@@dual-core0.elf@exe -Ibuild/hw-tests/dual-core/b5198ad@@dual-core1.elf@exe -Ibuild/../hw-tests/ecgtest -Ibuild/hw-tests/ecgtest/ -Ibuild/hw-tests/ecgtest/8ae72c4@@ecgtest.elf@exe -Ibuild/../hw-tests/hello-freertos -Ibuild/../hw-tests/hello-freertos/./ -Ibuild/hw-tests/hello-freertos/ -Ibuild/hw-tests/hello-freertos/./ -Ibuild/hw-tests/hello-freertos/b7270e9@@freertos-sdk@sta -Ibuild/hw-tests/hello-freertos/b7270e9@@hello-freertos.elf@exe -Ibuild/../hw-tests/hello-world -Ibuild/hw-tests/hello-world/ -Ibuild/hw-tests/hello-world/96b467b@@hello-world.elf@exe -Ibuild/../hw-tests/imutest -Ibuild/hw-tests/imutest/ -Ibuild/hw-tests/imutest/438301c@@imutest.elf@exe -Ibuild/../hw-tests/ips -Ibuild/hw-tests/ips/ -Ibuild/hw-tests/ips/3a8d6c1@@ips.elf@exe -Ibuild/../hw-tests/upy-minimal -Ibuild/hw-tests/upy-minimal/ -Ibuild/hw-tests/upy-minimal/59d35c7@@micropython@sta -Ibuild/hw-tests/upy-minimal/59d35c7@@upy-minimal.elf@exe -Ibuild/../lib/./card10/./ -Ibuild/../lib/card10 -Ibuild/lib/./card10/ -Ibuild/lib/./card10/./ -Ibuild/lib/./card10/7eaaaa5@@card10@sta -Ibuild/../lib/./gfx/./ -Ibuild/../lib/gfx -Ibuild/lib/./gfx/ -Ibuild/lib/./gfx/./ -Ibuild/lib/./gfx/2308dff@@gfx@sta -Ibuild/../lib/./gfx/./Fonts/ -Ibuild/../lib/./gfx/./GUI_DEV/ -Ibuild/../lib/./gfx/./LCD/ -Ibuild/../lib/./micropython/./micropython/ -Ibuild/../lib/./micropython/./micropython/extmod/ -Ibuild/../lib/./micropython/./micropython/lib/utils -Ibuild/../lib/sdk/Libraries/Boards/card10 -Ibuild/lib/./sdk/./Libraries/Boards/card10/ -Ibuild/lib/./sdk/./Libraries/Boards/card10/9eeeac4@@board-card10@sta -Ibuild/../lib/./sdk/./Libraries/Boards/card10/../Include/ -Ibuild/../lib/./sdk/./Libraries/Boards/card10/./Include/ -Ibuild/../lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665 -Ibuild/lib/./sdk/./Libraries/CMSIS/Device/Maxim/MAX32665/ -Ibuild/lib/./sdk/./Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core0@sta -Ibuild/lib/./sdk/./Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core1@sta -Ibuild/lib/./sdk/./Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup@sta -Ibuild/../lib/./sdk/./Libraries/FreeRTOS/../FreeRTOS-Plus/Source/FreeRTOS-Plus-CLI/ -Ibuild/../lib/./sdk/./Libraries/FreeRTOS/./Source/include/ -Ibuild/../lib/./sdk/./Libraries/FreeRTOS/./Source/portable/GCC/ARM_CM4F/ -Ibuild/../lib/sdk/Libraries/MAX32665PeriphDriver -Ibuild/lib/./sdk/./Libraries/MAX32665PeriphDriver/ -Ibuild/lib/./sdk/./Libraries/MAX32665PeriphDriver/0d96707@@PeriphDriver@sta -Ibuild/../lib/./sdk/./Libraries/MAX32665PeriphDriver/../CMSIS/Device/Maxim/MAX32665/Include/ -Ibuild/../lib/./sdk/./Libraries/MAX32665PeriphDriver/../CMSIS/Include/ -Ibuild/../lib/./sdk/./Libraries/MAX32665PeriphDriver/Include/ -Ibuild/../lib/vendor/Bosch/BHy1 -Ibuild/lib/./vendor/Bosch/BHy1/ -Ibuild/lib/./vendor/Bosch/BHy1/6298ab9@@bhy1@sta -Ibuild/../lib/./vendor/Bosch/BHy1/../../../card10/ -Ibuild/lib/./vendor/Bosch/BHy1/../../../card10/ -Ibuild/../lib/./vendor/Bosch/BHy1/./driver/inc/ -Ibuild/../lib/./vendor/Bosch/BHy1/./examples/firmware/ -Ibuild/../lib/./vendor/Bosch/BMA400/./ -Ibuild/../lib/vendor/Bosch/BMA400 -Ibuild/lib/./vendor/Bosch/BMA400/ -Ibuild/lib/./vendor/Bosch/BMA400/./ -Ibuild/lib/./vendor/Bosch/BMA400/b6b0216@@bma400@sta -Ibuild/../lib/./vendor/Bosch/BME680/./ -Ibuild/../lib/vendor/Bosch/BME680 -Ibuild/lib/./vendor/Bosch/BME680/ -Ibuild/lib/./vendor/Bosch/BME680/./ -Ibuild/lib/./vendor/Bosch/BME680/ef6f079@@bme680@sta -Ibuild/../lib/./vendor/Maxim/MAX77650/./ -Ibuild/../lib/vendor/Maxim/MAX77650 -Ibuild/lib/./vendor/Maxim/MAX77650/ -Ibuild/lib/./vendor/Maxim/MAX77650/./ -Ibuild/lib/./vendor/Maxim/MAX77650/cc369b8@@max77650@sta
flags = -DBOARD_CARD10=1 -D_FILE_OFFSET_BITS=64 -DTARGET=32665 -DTARGET_REV=0x4131 -target thumbv7m-none-eabi -Ibuild/epicardium -Ibuild/epicardium/366573f@@api-caller@sta -Ibuild/epicardium/366573f@@api-dispatcher@sta -Ibuild/epicardium/366573f@@epicardium.elf@exe -Ibuild/epicardium/366573f@@freertos@sta -Ibuild/lib/card10 -Ibuild/lib/card10/7eaaaa5@@card10@sta -Ibuild/lib/ff13 -Ibuild/lib/ff13/a277df3@@ff13@sta -Ibuild/lib/gfx -Ibuild/lib/gfx/2308dff@@gfx@sta -Ibuild/lib/micropython -Ibuild/lib/micropython/a57cd11@@mpy-cross-wrapper@exe -Ibuild/lib/mx25lba -Ibuild/lib/mx25lba/c7b864b@@mx25lba@sta -Ibuild/lib/sdk/Libraries/Boards/card10 -Ibuild/lib/sdk/Libraries/Boards/card10/9eeeac4@@board-card10@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665 -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core0@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core1@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup@sta -Ibuild/lib/sdk/Libraries/MAX32665PeriphDriver -Ibuild/lib/sdk/Libraries/MAX32665PeriphDriver/0d96707@@PeriphDriver@sta -Ibuild/lib/sdk/Libraries/MAXUSB -Ibuild/lib/sdk/Libraries/MAXUSB/9a51a91@@maxusb@sta -Ibuild/lib/vendor/Bosch/BHy1 -Ibuild/lib/vendor/Bosch/BHy1/6298ab9@@bhy1@sta -Ibuild/lib/vendor/Bosch/BMA400 -Ibuild/lib/vendor/Bosch/BMA400/b6b0216@@bma400@sta -Ibuild/lib/vendor/Bosch/BME680 -Ibuild/lib/vendor/Bosch/BME680/ef6f079@@bme680@sta -Ibuild/lib/vendor/Maxim/MAX77650 -Ibuild/lib/vendor/Maxim/MAX77650/cc369b8@@max77650@sta -Ibuild/lib/vendor/Maxim/MAX86150 -Ibuild/lib/vendor/Maxim/MAX86150/21e3a66@@max86150@sta -Ibuild/pycardium -Ibuild/pycardium/1f90fd2@@micropython@sta -Ibuild/pycardium/1f90fd2@@pycardium.elf@exe -Iepicardium -Ilib/card10 -Ilib/ff13 -Ilib/ff13/Source -Ilib/ff13/util -Ilib/FreeRTOS/Source/include -Ilib/FreeRTOS/Source/portable/GCC/ARM_CM4F -Ilib/gfx -Ilib/gfx/Fonts -Ilib/gfx/GUI_DEV -Ilib/gfx/LCD -Ilib/micropython -Ilib/micropython/micropython -Ilib/micropython/micropython/extmod -Ilib/micropython/micropython/lib/utils -Ilib/mx25lba -Ilib/sdk/Libraries/Boards/card10 -Ilib/sdk/Libraries/Boards/card10/Include -Ilib/sdk/Libraries/Boards/Include -Ilib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665 -Ilib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/Include -Ilib/sdk/Libraries/CMSIS/Include -Ilib/sdk/Libraries/MAX32665PeriphDriver -Ilib/sdk/Libraries/MAX32665PeriphDriver/Include -Ilib/sdk/Libraries/MAXUSB -Ilib/sdk/Libraries/MAXUSB/include/core -Ilib/sdk/Libraries/MAXUSB/include/core/musbhsfc -Ilib/sdk/Libraries/MAXUSB/include/dbg_log -Ilib/sdk/Libraries/MAXUSB/include/devclass -Ilib/sdk/Libraries/MAXUSB/include/enumerate -Ilib/sdk/Libraries/MAXUSB/include/util -Ilib/vendor/Bosch/BHy1 -Ilib/vendor/Bosch/BHy1/driver/inc -Ilib/vendor/Bosch/BHy1/examples/firmware -Ilib/vendor/Bosch/BMA400 -Ilib/vendor/Bosch/BME680 -Ilib/vendor/Maxim/MAX77650 -Ilib/vendor/Maxim/MAX86150 -Ipycardium -Ilib/ctx
# SPDX-License-Identifier: GPL-2.0
#
# (Adapted from the Linux kernel sources)
#
# clang-format configuration file. Intended for clang-format >= 4.
#
# For more information, see:
#
# Documentation/process/clang-format.rst
# https://clang.llvm.org/docs/ClangFormat.html
# https://clang.llvm.org/docs/ClangFormatStyleOptions.html
#
---
AccessModifierOffset: -4
AlignAfterOpenBracket: AlwaysBreak
AlignConsecutiveAssignments: true
AlignConsecutiveDeclarations: false
#AlignEscapedNewlines: Left # Unknown to clang-format-4.0
AlignOperands: true
AlignTrailingComments: true
AllowAllParametersOfDeclarationOnNextLine: true
# AllowAllArgumentsOnNextLine: true
AllowShortBlocksOnASingleLine: false
AllowShortCaseLabelsOnASingleLine: false
AllowShortFunctionsOnASingleLine: None
AllowShortIfStatementsOnASingleLine: false
AllowShortLoopsOnASingleLine: false
AlwaysBreakAfterDefinitionReturnType: None
AlwaysBreakAfterReturnType: None
AlwaysBreakBeforeMultilineStrings: true
AlwaysBreakTemplateDeclarations: false
BinPackArguments: false
BinPackParameters: false
BraceWrapping:
AfterClass: false
AfterControlStatement: false
AfterEnum: false
AfterFunction: true
AfterNamespace: true
AfterObjCDeclaration: false
AfterStruct: false
AfterUnion: false
#AfterExternBlock: false # Unknown to clang-format-5.0
BeforeCatch: false
BeforeElse: false
IndentBraces: false
#SplitEmptyFunction: true # Unknown to clang-format-4.0
#SplitEmptyRecord: true # Unknown to clang-format-4.0
#SplitEmptyNamespace: true # Unknown to clang-format-4.0
BreakBeforeBinaryOperators: None
BreakBeforeBraces: Custom
#BreakBeforeInheritanceComma: false # Unknown to clang-format-4.0
BreakBeforeTernaryOperators: false
BreakConstructorInitializersBeforeComma: false
#BreakConstructorInitializers: BeforeComma # Unknown to clang-format-4.0
BreakAfterJavaFieldAnnotations: false
BreakStringLiterals: false
ColumnLimit: 80
CommentPragmas: '^ IWYU pragma:'
#CompactNamespaces: false # Unknown to clang-format-4.0
ConstructorInitializerAllOnOneLineOrOnePerLine: false
ConstructorInitializerIndentWidth: 8
ContinuationIndentWidth: 8
Cpp11BracedListStyle: false
DerivePointerAlignment: false
DisableFormat: false
ExperimentalAutoDetectBinPacking: false
#FixNamespaceComments: false # Unknown to clang-format-4.0
#IncludeBlocks: Preserve # Unknown to clang-format-5.0
IncludeCategories:
- Regex: '.*'
Priority: 1
IncludeIsMainRegex: '(Test)?$'
IndentCaseLabels: false
#IndentPPDirectives: None # Unknown to clang-format-5.0
IndentWidth: 8
IndentWrappedFunctionNames: false
JavaScriptQuotes: Leave
JavaScriptWrapImports: true
KeepEmptyLinesAtTheStartOfBlocks: false
MacroBlockBegin: ''
MacroBlockEnd: ''
MaxEmptyLinesToKeep: 1
NamespaceIndentation: Inner
#ObjCBinPackProtocolList: Auto # Unknown to clang-format-5.0
ObjCBlockIndentWidth: 8
ObjCSpaceAfterProperty: true
ObjCSpaceBeforeProtocolList: true
# Taken from git's rules
#PenaltyBreakAssignment: 10 # Unknown to clang-format-4.0
PenaltyBreakBeforeFirstCallParameter: 30
PenaltyBreakComment: 10
PenaltyBreakFirstLessLess: 0
PenaltyBreakString: 10
PenaltyExcessCharacter: 100
PenaltyReturnTypeOnItsOwnLine: 60
PointerAlignment: Right
ReflowComments: false
SortIncludes: false
#SortUsingDeclarations: false # Unknown to clang-format-4.0
SpaceAfterCStyleCast: false
SpaceAfterTemplateKeyword: true
SpaceBeforeAssignmentOperators: true
#SpaceBeforeCtorInitializerColon: true # Unknown to clang-format-5.0
#SpaceBeforeInheritanceColon: true # Unknown to clang-format-5.0
SpaceBeforeParens: ControlStatements
#SpaceBeforeRangeBasedForLoopColon: true # Unknown to clang-format-5.0
SpaceInEmptyParentheses: false
SpacesBeforeTrailingComments: 1
SpacesInAngles: false
SpacesInContainerLiterals: false
SpacesInCStyleCastParentheses: false
SpacesInParentheses: false
SpacesInSquareBrackets: false
Standard: Cpp03
TabWidth: 8
UseTab: ForContinuationAndIndentation
...
---
Checks: 'clang-diagnostic-*,clang-analyzer-*,bugprone-*'
WarningsAsErrors: ''
HeaderFilterRegex: ''
AnalyzeTemporaryDtors: false
FormatStyle: none
User: swym
CheckOptions:
- key: cert-dcl16-c.NewSuffixes
value: 'L;LL;LU;LLU'
- key: cppcoreguidelines-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic
value: '1'
- key: google-readability-braces-around-statements.ShortStatementLines
value: '1'
- key: google-readability-function-size.StatementThreshold
value: '800'
- key: google-readability-namespace-comments.ShortNamespaceLines
value: '10'
- key: google-readability-namespace-comments.SpacesBeforeComments
value: '2'
- key: modernize-loop-convert.MaxCopySize
value: '16'
- key: modernize-loop-convert.MinConfidence
value: reasonable
- key: modernize-loop-convert.NamingStyle
value: CamelCase
- key: modernize-pass-by-value.IncludeStyle
value: llvm
- key: modernize-replace-auto-ptr.IncludeStyle
value: llvm
- key: modernize-use-nullptr.NullMacros
value: 'NULL'
...
target remote localhost:3333
define reset
mon mww 0x40000004 0x80000000
end
build/
card10.bin
/build/
/Documentation/output/
__pycache__/
*.pyc
.*.swp
*~
compile_commands.json
/tags
/release-*/
image: "debian"
# maintained by q3k, built using docker/build-env
image: "derq3k/card10-build-env:20190806-195837Z-f95b541-dirty"
build:
stage: build
before_script:
- echo "deb http://deb.debian.org/debian stretch-backports main" >> /etc/apt/sources.list
- apt update -qq
- apt install -y -qq gcc-arm-none-eabi python3-pip git
- apt install -y -qq -t stretch-backports meson
- pip3 install crc16
script:
- ./bootstrap.sh
script:
- git submodule deinit --all -f
- ./bootstrap.sh --werror
- ninja -C build/
- arm-none-eabi-size build/bootloader/bootloader.elf build/epicardium/epicardium.elf build/pycardium/pycardium.elf
- cp build/pycardium/pycardium_epicardium.bin card10.bin
only:
- merge_requests
- master
artifacts:
expose_as: Firmware Binaries
expire_in: 1 week
paths:
- build/epicardium/epicardium.elf
- build/pycardium/pycardium.elf
- card10.bin
release:
stage: build
script:
- git submodule deinit --all -f
- ./bootstrap.sh --werror
- ninja -C build/
- arm-none-eabi-size build/bootloader/bootloader.elf build/epicardium/epicardium.elf build/pycardium/pycardium.elf
only:
- tag
artifacts:
expire_in: never
paths:
- build/bootloader/bootloader.elf
- build/epicardium/epicardium.elf
- build/pycardium/pycardium.elf
- build/pycardium/pycardium_epicardium.bin
lint:
stage: test
image: "derq3k/card10-lint-env:20190806-201106Z-f95b541-dirty"
script:
# Annoyatron is maintained by q3k. Its job is to serve MR comments that are friendlier than just a failing pipeline.
# source code: https://git.card10.badge.events.ccc.de/q3k/annoyatron/
# prod deployment: https://gerrit.hackerspace.pl/plugins/gitiles/hscloud/+/refs/heads/master/personal/q3k/annoyatron/
# If this starts failing for any reason, just remove this curl ping.
- curl --fail https://annoyatron-prod.q3k.org/ping/mr?mr=${CI_MERGE_REQUEST_IID}
- git remote rm card10 || true # old gitlab runners might have this remote.
- git -c http.sslVerify=false fetch https://git.card10.badge.events.ccc.de/card10/firmware.git master:card10/master
- git merge-base card10/master HEAD || ( echo "Your change needs to be rebased against current master."; exit 1; )
- git diff --name-only --diff-filter=d card10/master...HEAD | xargs tools/code-style.sh
- git diff --exit-code
only:
- merge_requests
pages:
stage: deploy
# maintaned by q3k, build using docker/deploy-env
image: "registry.k0.hswaw.net/q3k/card10-deploy-env:20210403-110003Z-4d929ee0"
script:
- export LD_LIBRARY_PATH=$(llvm-config --libdir)
- echo $LD_LIBRARY_PATH
- sphinx-build -b html Documentation/ Documentation/output/
- mv Documentation/output/ public/
artifacts:
paths:
- public/
only:
- master
[submodule "lib/micropython/micropython"]
path = lib/micropython/micropython
url = https://github.com/micropython/micropython.git
[submodule "lib/micropython/micropython-lib"]
path = lib/micropython/micropython-lib
url = https://github.com/micropython/micropython-lib.git
[submodule "lib/crypto/tiny-AES-c"]
path = lib/crypto/tiny-AES-c
url = https://github.com/kokke/tiny-AES-c
[submodule "lib/crypto/SHA256"]
path = lib/crypto/SHA256
url = https://github.com/ilvn/SHA256
[submodule "lib/lodepng/lodepng"]
path = lib/lodepng/lodepng
url = https://github.com/lvandeve/lodepng
This diff is collapsed.
Copyright 2019 card10-firmware contributors
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.
.. _bluetooth_card10_service:
Bluetooth Card10 Service
========================
.. warning::
The specification is still work in progress
The Card10 Service implemented a direct Hardware access of the card10.
BLE Service
-----------
The current draft uses following service specification:
- Service
UUID: ``42230200-2342-2342-2342-234223422342``
- Time update characteristic:
UUID: ``42230201-2342-2342-2342-234223422342``
read and write no response
- Vibra characteristic:
UUID: ``4223020f-2342-2342-2342-234223422342``
write no response
- Rockets characteristic:
UUID: ``42230210-2342-2342-2342-234223422342``
read and write no response
- Background LED Bottom Left characteristic:
UUID: ``42230211-2342-2342-2342-234223422342``
read and write no response
- Background LED Bottom Right characteristic:
UUID: ``42230212-2342-2342-2342-234223422342``
read and write no response
- Background LED Top Right characteristic:
UUID: ``42230213-2342-2342-2342-234223422342``
read and write no response
- Background LED Top Left characteristic:
UUID: ``42230214-2342-2342-2342-234223422342``
read and write no reponse
- LEDS dim bottom characteristic:
UUID: ``42230215-2342-2342-2342-234223422342``
write with response
- LEDs dim top characteristic:
UUID: ``42230216-2342-2342-2342-234223422342``
write with response
- LEDs powersafe characteristic:
UUID: ``42230217-2342-2342-2342-234223422342``
write no response
- Flashlight characteristic:
UUID: ``42230218-2342-2342-2342-234223422342``
write no response
- Personal State characteristic:
UUID: ``42230219-2342-2342-2342-234223422342``
read and write with response
- LEDs above characteristic:
UUID: ``42230220-2342-2342-2342-234223422342``
read and write no reponse
- Light sensor characteristic:
UUID: ``422302f0-2342-2342-2342-234223422342``
read no response
Time update characteristic
---------------------------------
The time update characteristic makes it possible to set and get the current time given in milliseconds after 1.1.1970 in the UTC timezone. The value is represented as a big endian ``uint64``
- Thu Aug 15 19:40:45 UTC 2019 : ``0x0 0x0 0x1 0x6c 0x96 0xcb 0xf8 0xcc``
Vibra characteristic
---------------------------------
The vibra characteristic makes it possible to let the card10 for given millisecound in a ``uint16`` vibrate.
- One secound: ``0xe803``
Rockets characteristic
---------------------------------
The Rockets characteristic makes it possible to address every three rockets.
Just write there three byte array, one for evey rocket.
On read you get the current value of all three rockets.
Range is between 0 and 31 (``0x1f``) if send higher value it will set to max of 31.
Dataformat:
======= ======= =======
0 1 2
------- ------- -------
Rocket0 Rocket1 Rocket2
======= ======= =======
- Enable only Rocket0: ``0x1f0000``
- Enable all rockets with 50% brightness: ``0x0f0f0f``
Background LED <Position> characteristic
----------------------------------------
The Background LEDs <Position> characteristic makes it possible to address the bottom LEDs by position.
Just write there three ``uint8`` for the rgb color or read the current value.
Dataformat:
===== ======= =======
0 1 2
----- ------- -------
red green blue
===== ======= =======
- set led blue: ``0x0000ff``
- disabled: ``0x000000``
LEDs dim <Position> characteristic
----------------------------------
The LEDs dim <Position> characteristic makes it possible to dim LEDs by position.
Just write a ``uint8`` between ``1`` and ``8``.
LEDs powersafe characteristic
---------------------------------
This characteristic makes it possible to set the LEDs in powersafe mode.
Even when set to zero, the RGB LEDs still individually consume ~1mA.
Powersave intelligently switches the supply power in groups.
This introduces delays in the magnitude of ~10µs, so it can be disabled for high speed applications such as POV
- enabled: ``0x01``
- disabled: ``0x00``
Flashlight characteristic
---------------------------------
This characteristic makes it possible to activate the flashlight.
- enabled: ``0x01``
- disabled: ``0x00``
Personal state characteristic
---------------------------------
This characteristic makes it possible to read and write the personal state.
It writes always as persistant and it gives feedback if the value is in range and your firmware support it.
- No State ``0x0000``
- No Contact ``0x0100``
- Chaos ``0x0200``
- ...
LEDs above characteristic
---------------------------------
This characteristic set or read the current value of every 11 leds on the top module at once.
By defining 11x rgb from left to right. You need also to set exchange a bigger MTU to use this feature.
- set a rainbow beginnig with red on the right edge: ``0xff0000ff8b00e8ff005dff0000ff2e00ffb900b9ff002eff5d00ffe800ffff008b``
Light sensor characteristic
---------------------------------
The light sensor characteristic makes it possible to read the current value of the light sensor by receiving a ``uint16``.
The range of this sensor is between 0 (``0x0``) and 400 (``0x9001``).
- reading of ``0x0e00`` means **14**
Access via btgatt-client
---------------------------------
Accessing services from a linux system is possible via ``btgatt-client``. The inbuilt gatt client of ``bluetoothctl`` as well as ``libgatt`` were tested, but struggled with the card10's BLE stack.
**Example**:
.. code-block::
# pairing the card10:
$ bluetoothctl
[bluetooth]# power on
[bluetooth]# scan on
[bluetooth]# pair CA:4D:10:xx:xx:xx #replace xx:xx:xx with scan result
# if this query doesn't appear, remove and re-pair:
[agent] Confirm passkey ###### (yes/no): [CHG] Device CA:4D:10:xx:xx:xx Name: card10
[card10-xxxxxx]# disconnect CA:4D:10:xx:xx:xx
# using a service:
$ btgatt-client -d CA:4D:10:xx:xx:xx
# wait until services have been discovered, may take a minute
[GATT client]# write-value 0x0926 31 31 31
# if this error appears remove and re-pair:
[GATT client]# Device disconnected: Software caused connection abort
ARM Cordio Sources
------------------
The BLE stack is based on the ARM Cordio stack. This stack has been developed by a 3rd party and was bought by ARM and open-sourced.
There are many copies of it floating around on the Internet and some are more up to date than others. To keep track here is a list:
- mbed
- mbed has a reasonably up to date version of the stack in their GitHub repository.
- It is scattered below the CORDIO directories in https://github.com/ARMmbed/mbed-os/tree/master/features/FEATURE_BLE/targets
- ble-profiles are not included. mbed has written their own adaptation layer to interface with the stack and implements profiles in C++
- Ambiq Suite SDK
- Can be found here: https://github.com/sparkfun/AmbiqSuiteSDK/tree/master/third_party/exactle
- Patches on top might be here: https://support.ambiqmicro.com/hc/en-us/categories/115000239012-Software
- Reasonably up to date
- Intersting part: has their own FreeRTOS integration (but apparently on older WSF)
- BLE 5.1 (?)
- Packetcraft
- Apparently tasked with maintaining the stack in general
- Most up to date version
- https://github.com/packetcraft-inc/cordio
- Apparently developing (security) fixes, distributing them to customers, but not applying them to master: https://github.com/ARMmbed/mbed-os/commit/c92777311578eb003b4546c4e5e6f2c1f8ba3c84
- BLE 5.1
- Maxim
- Distributed via Maxim Toolchain Installation tool, no repository available
- Contains software implementation of the base band
- ble-host and ble-profiles might be compatible with the one directly from Packetcraft
- Developing their own low-power enhancements
- BLE 5.0
.. _bluetooth_ecg_service:
Bluetooth ECG Service
========================
.. warning::
The service is still work in progress and subject to change
The ECG service provides access to the ECG sensor of the card10
BLE Service
-----------
The current draft uses following service specification:
- Service:
UUID: ``42230300-2342-2342-2342-234223422342``
- ECG samples characteristic:
UUID: ``42230301-2342-2342-2342-234223422342``
notify
ECG samples characteristic
--------------------------
List of 16 bit samples (big endian). Enable notifications to
receive a stream of samples while the ECG app is open.
The first 16 bit are a sample counter (big endian).
.. _ESS:
Environmental Sensing Service
=============================
The Environmental Sensing Service (ESS) implements access to
the BME680 environmental sensor of the card10.
It provides:
- Temperature
- Relative humidity
- Pressure
If :ref:`bsec_api` is enabled the following additional estimates are available:
- Indoor air quality (IAQ estimate
- Equivalent CO2 (eCO2) estimate
Please refer to :py:mod:`bme680` for more information about BSEC.
If notifcations are enabled a measurement of all values is performed every 3 seconds. For each measurement a notification is sent for the characteristics which have notifications enabled.
A measurement can also be triggered by reading from a characteristic. A measurement takes roughly 200 ms. A notifciation will be sent to all characteristics which have notifications enabled except the one which was used to trigger the measurement.
.. note::
If :ref:`bsec_api` is enabled, reading a characteristic will not trigger a new measurement.
.. note::
This service will be available in version v1.17.
BLE Service
-----------
- Service
UUID: ``181A``
- Temperature characteristic:
UUID: ``2A6E``
read and notify
- Humidity characteristic:
UUID: ``2A6F``
read and notify
- Pressure characteristic:
UUID: ``2A6D``
read and notify
- Indoor air quality (IAQ) characteristic:
UUID: ``422302f1-2342-2342-2342-234223422342``
read and notify
Temperature characteristic
--------------------------
- 16 bit little endian value representing the measured temperature.
- Unit: 0.01 deg C
Humidity characteristic
-----------------------
- 16 bit little endian value representing the measured relative humidity.
- Unit: 0.01%
Pressure characteristic
-----------------------
- 32 bit little endian value representing the measured pressure.
- Unit: 0.1 Pa (0.001 hPa)
Indoor air quality (IAQ) characteristic
---------------------------------------
Data format:
======== =========================== ===========================
Byte 0 Bytes 1-2 Bytes 3-4
-------- --------------------------- ---------------------------
Accuracy IAQ (16-bit little endian) eCO2 (16-bit little endian)
======== =========================== ===========================
Units:
- Accuracy and IAQ units: See :ref:`bsec_api` API description
- CO2 unit: [ppm]
.. _bluetooth_file_transfer:
Bluetooth File Transfer
=======================
.. warning::
The file transfer specification is still work in progress
File transfer to the card10 is implemented using the custom Low Effort File
Transfer Protocol.
BLE Service
-----------
The service consists of two GATT characteristics that act as a bidrectional
link, similar to many BLE UART implementations. The two channels are seen from
the Central perspective and hence named Central TX and Central RX.
The current version uses following service specification:
- Service
UUID: 42230100-2342-2342-2342-234223422342
- Central TX characteristic:
UUID: 42230101-2342-2342-2342-234223422342
write
- Central RX characteristic:
UUID 42230102-2342-2342-2342-234223422342
read, notify
Low Effort File Transfer Protocol
---------------------------------
(Version 1)
This protocol was designed to strike a balance between ease of implementation
and reasonable levels of functionality.
Features:
- File push from Central (e.g. Android) to Peripheral (card10)
- Path and file name support
- Chunked data transfer for variable MTUs
- CRC32 error-detection
- Basic error handling
All communication between Central and Peripheral is packet based. The first
byte specifies the packet type using a char followed by an optional CRC and/or
payload, depending on the packet type.
START:
===== ====
0 1-N
----- ----
s path
===== ====
START_ACK:
===== ===
0 1-4
----- ---
S CRC
===== ===
CHUNK:
===== ====== =======
0 1-4 4-N
----- ------ -------
c offset payload
===== ====== =======
CHUNK_ACK:
===== ===
0 1-4
----- ---
C CRC(*)
===== ===
CRC32 of the whole CHUNK packet including first byte, offset and payload.
FINISH:
=== ===
0
--- ---
f
=== ===
FINISH_ACK:
=== ===
0
--- ---
F
=== ===
ERROR:
=== ===
0
--- ---
e
=== ===
ERROR_ACK:
=== ===
0
--- ---
E
=== ===
Flow
----
The file transfer process can be described as a series of states from the view
of the Central role:
.. image:: ../static/ble-low-effort-flow.png
``IDLE`` state:
- Send ``START`` to initiate transfer
``START_SENT`` state:
- Wait for ``START_ACK``
``SEND_READY`` state:
- Send first ``CHUNK``
``CHUNK_SENT`` state:
- Wait for ``CHUNK_ACK``
``SEND_READY`` state:
- Repeat previous two steps until all data is sent
- If the last chunk was sent, send ``FINISH``
``FINISH_SENT`` state:
- Wait for ``FINISH_ACK``
After ``FINISH_ACK`` was received, the transfer is complete and the process can
return to ``IDLE``.
Error Handling
--------------
Three types of errors are currently supported:
- CRC errors:
If an ``ACK`` packet contains a CRC that fails the verification, then the
original packet must be retransmitted. If three consecutive attempts to
send a packet fail, then the transfer is aborted.
- ACK timeouts:
If the Central does not receive a required ``ACK`` within 10 seconds, then
the original packet must be retransmitted. If three consecutive attempts to
send a packet fail, then the transfer is aborted.
- Unexpected response:
All steps in the flow described above have exactly one expected response.
If any other packet is received, then the transfer is aborted.
Aborting Transfer
-----------------
To abort the transfer, the Central role sends an ``ERROR`` packet and returns
to ``IDLE`` after receiving the ``ERROR_ACK``.
If the Peripheral role aborts the transfer, i.e. the Central receives an
``ERROR`` at any point, then it responds with ``ERROR_ACK`` and returns to
``IDLE``
.. warning::
As this is a custom file transfer protocol developed under less than ideal
circumstances, it does not provide any guarantees, especially not regarding
reliability or security. The protocol assumes a secure link and a
trustworthy peer, amongst many other things. Use with caution.
NimBLE
======
On the card10 the ARM Cordio-B50 stack is used, which is in a very early experimental state and has some incompatibilities with some smartphones.
Therefore some alternative stacks are evaluated, which meight be used as a replacement in the long term.
Here a stack called NimBLE is presented, which claims to be feature complete. Originally it has been developed for Mynewt, an open source embedded operating system by Apache (https://mynewt.apache.org/).
There is a working port for the ESP32 espressif ESP-IDF framework.
Like Epicardium, ESP-IDF is based on FreeRTOS. Therefore it can be used for evaluation purposes.
Getting NimBLE run on the ESP32
-------------------------------
Install required packages:
Ubuntu:
.. code-block:: shell-session
sudo apt install git virtualenv python2.7 cmake
Arch:
.. code-block:: shell-session
sudo pacman -S git python2 python2-virtualenv cmake
Download and extract xtensa ESP32 compiler:
.. code-block:: shell-session
wget https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp32-2018r1-linux-amd64.tar.xz
tar -xf xtensa-esp32-elf-gcc8_2_0-esp32-2018r1-linux-amd64.tar.xz
Clone esp-idf:
.. code-block:: shell-session
git clone https://github.com/espressif/esp-idf.git
Add xtensa and ESP-IDF path to $PATH:
bash shell:
.. code-block:: shell-session
export IDF_PATH=$PWD/esp-idf
export PATH=${PATH}:$PWD/xtensa-esp32-elf/bin:$PWD/esp-idf/tools
fish shell:
.. code-block:: shell-session
set -gx IDF_PATH $PWD/esp-idf
set -gx PATH $PWD/xtensa-esp32-elf/bin/ $PWD/esp-idf/tools $PATH
Create a python2.7 virtualenv:
.. code-block:: shell-session
cd esp-idf
virtualenv -p /usr/bin/python2.7 venv
Enter the virtualenv:
bash shell:
.. code-block:: shell-session
. venv/bin/activate
fish shell:
.. code-block:: shell-session
. venv/bin/activate.fish
Init git submodules and install all required Python packages:
.. code-block:: shell-session
git submodule update --init --recursive
pip install -r requirements.txt
Now you are ready to build!
The following steps assume that your ESP32 is connected via USB and
is accessible via /dev/ttyUSB0. This meight be different on your system.
There are a few NimbLE examples which can be used for playing around:
Build a BLE server example (host mode):
---------------------------------------
.. code-block:: shell-session
cd examples/bluetooth/nimble/bleprph
idf.py -p /dev/ttyUSB0 flash monitor
This will build and flash the example to the ESP32 and instantly listens on /dev/ttyUSB0 serial port.
After the flashing process the ESP32 will anounce itself as **nimble-bleprph** device via BLE.
Build a BLE client example (central mode):
------------------------------------------
.. code-block:: shell-session
cd examples/bluetooth/nimble/blecent
idf.py -p /dev/ttyUSB0 flash monitor
This will build and flash the example to the ESP32 and instantly listens on /dev/ttyUSB0 serial port.
After the flashing process the ESP32 creates a GATT client and performs passive scan, it then connects to peripheral device if the device advertises connectability and the device advertises support for the Alert Notification service (0x1811) as primary service UUID.
.. _bluetooth_overview:
Overview
========
UUIDs
-----
Bluetooth uses UUIDs to identify almost everything. The Bluetooth SIG specifies
a number of "short" 16-bit UUIDs for general use. A device is free to define
other "long" 128-bit UUIDs if it wants to express non-standard functionality.
The card10 defines a few non-standard UUIDs. They are prefixed with ``4232``:
+--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
| UUID | Usage | Comment |
+======================================+=======================================================+====================================================================+
| 422301XX-2342-2342-2342-234223422342 | :ref:`File Transfer Service<bluetooth_file_transfer>` | Used by the Companion App to install apps on the card10 |
+--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
| 422302XX-2342-2342-2342-234223422342 | :ref:`card10 Service<bluetooth_card10_service>` | Controls general card10 functionality like LEDs and personal state |
+--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
| 422303XX-2342-2342-2342-234223422342 | :ref:`ECG Service<bluetooth_ecg_service>` | Allows to stream ECG measurements via BLE |
+--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
| 422380XX-2342-2342-2342-234223422342 | Experimental usage | To be used for development and experiments |
+--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
The first byte after the prefix identifies the service (e.g. ``03`` for ECG).
The next byte is reserved for UUIDs used by the service itself. The service
uses ``00`` at this position. The first attribute inside the service uses
``01`` at this position. See the documentation of any service for an example.
You can use the UUID range 422380XX-2342-2342-2342-234223422342 for your own
experiments / demos/ development. For example the demos under `demos/` in the
repository use this range of UUIDs.
BLE with MicroPython
--------------------
MicroPython docs: https://docs.micropython.org/en/latest/library/bluetooth.html
Basic example: https://git.card10.badge.events.ccc.de/card10/firmware/-/blob/master/demos/ble-ws2812-card10.py and https://git.card10.badge.events.ccc.de/card10/firmware/-/blob/master/demos/ble-ws2812-host.py
MicroPython examples: https://github.com/micropython/micropython/tree/7c54b6428058a236b8a48c93c255948ece7e718b/examples/bluetooth
#!/bin/bash
set -e
cd "$(dirname "$0")"
sphinx-build -b html . ./output
if [ "$1" = "--open" ]; then
xdg-open ./output/index.html
fi
.. _card10_cfg:
card10.cfg
==========
Certain high-level settings can be configured using a filed named ``card10.cfg``. It is accessed from the :ref:`usb_file_transfer` of the bootloader. Once you are in this mode and have mounted the badge's flash device, you can either create or update a file named ``card10.cfg``.
The file is in the well-known INI-style format, with one setting per line. For instance, if there were an option called ``answer_to_life``, you could set it by writing the following line in the ``card10.cfg`` file:
.. code-block:: text
answer_to_life = 42
Don't forget to unmount the filesystem before rebooting your badge after changing any setting.
Syntax and Types
----------------
Lines that start with a ``#`` character are ignored.
Any other line will have the overall syntax of ``option_name = option_value``, with spaces around the ``=`` character optional.
Option names are internal to card10 and described below. Each option has a defined type.
========= ===========
Type name Description
========= ===========
Boolean A true/false value. ``1`` or ``true`` is true, ``0`` or ``false`` is false. Example: ``foo = true``.
String An unquoted string value of maximum 20 bytes. Values longer than 20 bytes are trimmed. Example: ``foo = bar``.
Integer A signed 32-bit integer in base 10. Example: ``foo = 42`` or ``bar = -1337``.
Float A single-precision (32-bit) floating-point number in base 10. Example: ``foo = 13.37``.
========= ===========
Supported options
-----------------
================== ========== ===========
Option name Type Description
================== ========== ===========
``execute_elf`` Boolean Allow running of binary :ref:`l0dables`. These files can be nefarious, so this option is off by default.
------------------ ---------- -----------
``timezone`` String Timezone for card10; must be of format ``[+-]HHMM``. Examples: ``+0800``, ``-0200``
------------------ ---------- -----------
``default_app`` String Full path to the exectutable file of the default application. If this option is not set,``apps/analog_clock/__init__.py`` is used.
------------------ ---------- -----------
``ble_enable`` Boolean Activate the BLE interface. Turn off for more privacy or to conserve energy.
------------------ ---------- -----------
``ble_mac`` Boolean MAC address used for BLE. Format: ``ca:4d:10:xx:xx:xx``.
------------------ ---------- -----------
``ble_hid_enable`` Boolean Enable the Human Interface Device (HID) characteristics on BLE.
------------------ ---------- -----------
``ble_log_enable`` Boolean Activate HCI level logging of BLE data. Creates a new btsnoop compatible log file named ``ble.log`` in the ``logs`` folder after each boot if BLE is activated. Keeps the last 10 files.
------------------ ---------- -----------
``right_scroll`` Boolean Use both right buttons to scroll up and down. Lower left button is SELECT.
------------------ ---------- -----------
``long_press_ms`` Integer Defines the timespan for a long key press in milliseconds.
------------------ ---------- -----------
``retrigger_ms`` Integer Defines the timespan for repeating key presses when a key is hold in milliseconds.
------------------ ---------- -----------
``bsec_enable`` Boolean Activate the Bosch :ref:`bsec_api` binary blob to compute an Indoor Air Quality indication.
------------------ ---------- -----------
``bsec_debug`` Boolean Turn on debug output of the BSEC system. Prints each meaurement on the console.
------------------ ---------- -----------
``bsec_offset`` Integer Temperature offset in .1 K. Example: Set to `-14` if temperature reads 1.4 "C" to high. Default: -2.2 K (appropriate for a card10 without a case, connected to USB and with BLE active in vertical orientation).
------------------ ---------- -----------
``battery_check`` Boolean Whether the low battery check should be enabled (default ``true``). **Warning**: Do not use this unless you know what you're doing. This option is only meant to be used on devices with a broken PMIC ADMUX connection.
------------------ ---------- -----------
``has_flashlight`` Boolean Whether the flashlight LED was soldered onto the harmonic board. Can be used by apps to optionally enable flashlight features.
================== ========== ===========
import os
import subprocess
import sys
import time
import sphinx.util.logging
from docutils import nodes
from docutils.parsers import rst
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
sys.path.insert(0, os.path.abspath("../pycardium/modules/py"))
sys.path.insert(0, os.path.abspath("./"))
logger = sphinx.util.logging.getLogger("card10/conf.py")
# -- Project information -----------------------------------------------------
project = "card10-firmware"
copyright = "2019"
# The full version, including alpha/beta/rc tags
release = (
subprocess.check_output(["git", "describe", "--long", "--always"]).decode().strip()
)
release += "<br />"
release += time.strftime("%F %R")
version = release
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.viewcode",
"sphinx.ext.ifconfig",
"sphinx.ext.todo",
]
todo_include_todos = True
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["output", "Thumbs.db", ".DS_Store", "hawkmoth"]
# -- Extensions -------------------------------------------------------------- {{{
class ColorExample(rst.Directive):
has_content = False
required_arguments = 1
optional_arguments = 0
option_spec = {}
def run(self):
color = self.arguments[0]
html_text = '<div style="width: 30px;height: 30px;background: {};border: black 1px solid;border-radius: 15px;"></div>'
return [nodes.raw("", html_text.format(color), format="html")]
# }}}
# -- Options for HTML output ------------------------------------------------- {{{
# The Read the Docs theme is available from
# - https://github.com/snide/sphinx_rtd_theme
# - https://pypi.python.org/pypi/sphinx_rtd_theme
# - python-sphinx-rtd-theme package (on Debian)
try:
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
pygments_style = "monokai"
except ImportError:
logger.warning(
'The Sphinx "sphinx_rtd_theme" HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.'
)
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["static"]
# Theme Options
html_theme_options = {"style_external_links": True}
# Show "Edit on GitLab" links
html_show_sourcelink = False
html_context = {
"display_gitlab": True,
"gitlab_host": "git.card10.badge.events.ccc.de",
"gitlab_user": "card10",
"gitlab_repo": "firmware",
"gitlab_version": "master/",
"conf_py_path": "Documentation/",
"theme_vcs_pageview_mode": "edit",
}
# }}}
# -- Options for Auto-Doc ---------------------------------------------------- {{{
autodoc_mock_imports = [
"buttons",
"interrupt",
"sys_ble_hid",
"sys_bme680",
"sys_bhi160",
"sys_display",
"sys_leds",
"sys_max30001",
"sys_max86150",
"sys_png",
"sys_config",
"ucollections",
"uerrno",
"urandom",
"utime",
]
autodoc_member_order = "bysource"
# }}}
# -- Options for Hawkmoth ---------------------------------------------------- {{{
has_hawkmoth = False
try:
# Attempt importing hawkmoth
import hawkmoth # noqa: F401
extensions.append("hawkmoth")
cautodoc_root = os.path.abspath("..")
cautodoc_clang = "-D__SPHINX_DOC"
has_hawkmoth = True
except ImportError as e:
if e.name == "clang":
logger.warning(
"hawkmoth requires the clang python module. Documentation for Epicardium API will not be generated."
)
# }}}
# -- Sphinx Setup ------------------------------------------------------------
def setup(app):
app.add_config_value("has_hawkmoth", has_hawkmoth, "")
app.add_directive("color-example", ColorExample)
fix_issue_8945()
def fix_issue_8945():
c_domain = __import__("sphinx.domains.c").domains.c
for kw in [
"char",
"float",
"int",
"long",
"short",
"void",
"_Bool",
"bool",
"_Complex",
"complex",
]:
if kw in c_domain._keywords:
c_domain._keywords.remove(kw)
if hasattr(c_domain, "_macroKeywords") and kw in c_domain._macroKeywords:
c_domain._macroKeywords.remove(kw)
def parse_xref_object(self):
name = self._parse_nested_name()
self.skip_ws()
self.skip_string("()")
# Removing this line as a hacky workaround:
# self.assert_end()
return name
c_domain.DefinitionParser.parse_xref_object = parse_xref_object
.. _debugger:
Debugger
========
If you have one of our debuggers for card10, this page details how you can use
it. The debugger looks like either one in the following pictures:
.. image:: static/debuggers.png
First of all, you need to connect your debugger and card10. There are three
connections that you need (take a look at the above diagram for more info):
* ``HDK``: This connection provides debugging (SWD) and UART.
* ``DEV``: This connection provides power (battery charger) and the native USB
connection (bootloader).
* ``USB-C``: Connect the proved USB-C cable with the side which has the blue
dot, so the blue dots have the same side.
Console
-------
When using the debugger, you will usually have two /dev/ttyACM* devices (one
each for ``HDK`` and ``DEV``). To avoid confusion, allow access without
``sudo`` and tell ModemManager to ignore them, you can use the following udev
rule file (saved under ``/etc/udev/rules.d/99-card10.rules``):
.. code-block:: text
SUBSYSTEM=="tty", ATTRS{idVendor}=="0d28", ATTRS{idProduct}=="0204", MODE="0664", GROUP="plugdev", SYMLINK+="ttyACM-card10-hdk", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="tty", ATTRS{idVendor}=="0b6a", ATTRS{idProduct}=="003c", MODE="0664", GROUP="plugdev", SYMLINK+="ttyACM-card10-dev", ENV{ID_MM_DEVICE_IGNORE}="1"
After changing udev rules, you need to tell the udev daemon:
.. code-block:: shell-session
$ sudo udevadm control --reload
Now, additional symlinks (``/dev/ttyACM-card10-hdk`` and
``/dev/ttyACM-card10-dev``) will be created when connecting the card10.
OpenOCD
-------
For debugging card10, you need our `own fork`_ of OpenOCD. It contains a patch
which allows flashing both flash-banks instead of just one. Install it using
the following commands:
.. _own fork: https://git.card10.badge.events.ccc.de/card10/openocd
.. code-block:: shell-session
$ git clone --recursive https://git.card10.badge.events.ccc.de/card10/openocd.git
$ cd openocd
$ ./bootstrap
$ ./configure --disable-werror
.. warning::
Make sure ``CMSIS-DAP Compliant Debugger`` is set to **yes (auto)** after
running ``./configure`` (if it is not, you might need to install ``libhidapi-dev``
(Ubuntu)). If you get errors making the documentation you can
``touch doc/openocd.info`` to skip it and continue with ``make``.
.. code-block:: shell-session
$ make -j8
Please run ``make install`` after removing any already installed OpenOCD
version. Otherwise please always specify the full path to OpenOCD (the binary
is under ``src/openocd``).
.. note::
If you want to use OpenOCD as normal user, copy ``contrib/60-openocd.rules``
into the ``/etc/udev/rules.d/`` directory and run ``udevadm control --reload``
afterwards.
GDB (``arm-none-eabi-gdb``)
---------------------------
Apart from OpenOCD you also need ``arm-none-eabi-gdb``. You should install
that package from your distros repositories:
* Ubuntu (older): ``gdb-arm-none-eabi``
* Ubuntu (newer): ``gdb-multiarch``
* Arch: ``arm-none-eabi-gdb``
Debugging
---------
Run OpenOCD from the ``openocd/scripts`` directory in the firmware repository.
Call it as ``openocd -f interface/cmsis-dap.cfg -f target/max32665.cfg``. If
the debugger and card10 are connected correctly, you should see the following
output:
.. code-block:: shell-session
$ openocd -f interface/cmsis-dap.cfg -f target/max32665.cfg
Info : CMSIS-DAP: SWD Supported
Info : CMSIS-DAP: FW Version = 1.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 0 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : clock speed 2000 kHz
Info : SWD DPIDR 0x2ba01477
Info : max32xxx.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : Listening on port 3333 for gdb connections
Next, start *GDB* in parallel and connect it to OpenOCD. You can do this easily
if you run GDB from the firmware repository root where we have provided an
``init.gdb`` file. Specify ``-x init.gdb`` to use this file. Apart from
automatically connecting to OpenOCD, this script file also defines a ``reset``
command to soft-reset card10.
.. code-block:: shell-session
$ arm-none-eabi-gdb -x init.gdb build/hw-tests/hello-world/hello-world.elf
...
(gdb)
.. note::
You will also find the following self-describing gdb files in the firmware
root directory, which do not require additional arguments:
``flash-all.gdb, flash-bootloader.gdb,
flash-both.gdb, flash-epicardium.gdb, flash-pycardium.gdb``
.. warning::
If you are used to use ``mon reset halt``, be aware that the card10 prototypes
do not connect the reset line to the debugger. OpenOCD is configured to only do
a soft-reset. This reset only resets the core, but not its peripherals.
Our custom ``reset`` sets a special bit in the CPU which also resets the
peripherals.
You are now connected to card10 and ready to start debugging! If card10 is
still running, stop it using
.. code-block:: text
(gdb) mon reset halt
Following that, you can debug as you would normally.
.. _epicardium_api_guide:
Epicardium API Development
==========================
If you are interested in augmenting the Epicardium API with new calls, this
page is the right place for you.
API Call Declaration
--------------------
All API calls are declared in ``epicardium/epicardium.h``. We also generated
documentation for all API calls using sphinx. Please document any new calls in
the same format as existing calls. An example API call definition might look
like this:
.. code-block:: cpp
/* At the top of epicardium.h, add a unique ID for your call */
#define API_ROCKET 0xc0ffee
/**
* Turn on card10's rocket engines.
*
* :param force: Force in Newtons.
* :param color: 24-bit exhaust color.
* :return: ``0`` on success or ``-Exxx`` on error. The following errors
* might occur:
*
* - ``-ENODEV``: Sadly, card10 does not have rocket engines.
*/
API(API_ROCKET, int epic_rocket_start(float force, uint32_t color));
There are a number of rules you should follow when defining new calls:
* Each API call need a unique call number (``API_ROCKET`` in this case).
There are no special rules regarding call numbers, choose any number not yet
in use. Call numbers are ``uint32_t`` so you have plenty to choose from.
* API calls have the prefix ``epic_`` which of course is just an abbreviation
for *Epicardium*.
* Only use types from the standard library or types defined (and documented!)
in ``epicardium.h``. **Never** include another header in ``epicardium.h``.
* When passing pointers, keep in mind that this will mean the other core will
potentially modify stuff in your address space. Please prefer passing pointers
into core 1 (Pycardium) address space and refrain from returning pointers into
Epicardium address space if possible.
* API calls follow the kernel convention of either returning a boolean if the
name is a predicate or a success integer (with 0 denoting success and
negative values denoting errors) if they are an imperative command or action
(ref `Kernel Coding Style`_). If you are reasonably sure your call cannot fail
or an error is non-recoverable from core 1, return ``void``.
.. _Kernel Coding Style: https://www.kernel.org/doc/html/v5.2/process/coding-style.html#function-return-values-and-names
.. warning::
After the 4th of August 00:00 UTC, **no** changes to existing IDs and the signature
and behavior of existing calls are allowed! This is necessary to ensure
compatibility of future firmware versions with older payloads. We call this
date the **API Freeze Deadline**. Addition of new calls will always be allowed.
In return this also means payloads compiled against a version of *Epicardium
API* released before that date are not guaranteed to work during and after
camp.
API Call Definition
-------------------
API calls should be defined in a source file in ``epicardium/modules``. If
there is not yet one where your call fits in, create a new one. Don't forget
to also add it in ``epicardium/modules/meson.build`` to make the build-system
aware of it.
For the example above, the definition might look like this:
.. code-block:: cpp
/* epicardium/modules/rocket.c */
#include <stdio.h>
#include "epicardium.h"
int epic_rocket_start(float force, uint32_t color)
{
printf("Starting rocket engines with %fN in color 0x%x"
force,
color);
/* Aw :( */
return -ENODEV;
}
To keep code-style uniform across the project, please format your code using
``./tools/code-style.sh <filename>`` (requires ``clang-format``). Note that
this is not a definite style, however: If something looks better when manually
formatted, don't be afraid to do so.
.. warning::
When writing your calls, **never** make assumptions about which FreeRTOS
task you are running in. While all calls from core 1 will end up in the
"Dispatcher" task, other FreeRTOS tasks might might call your code at any
time just as well.
This is especially important if you use a `task semaphore`_. Always call
``xTaskGetCurrentTaskHandle()``.
.. _task semaphore: https://freertos.org/RTOS_Task_Notification_As_Binary_Semaphore.html