Skip to content

Commit 59fd091

Browse files
dezren39dezren39
committed
Improve Scripts & Docs
* update comments * rename to beepy * Create Dockerfile * Update dbuild.sh * Create lib.sh * improve * Update and rename initialize-repo.sh to initialize-submodules.sh * reset submodules * +x * improve init * reset * build * rename * init when needed * improve readme * improve scripts * Delete Dockerfile
1 parent c1c9b23 commit 59fd091

File tree

5 files changed

+228
-15
lines changed

5 files changed

+228
-15
lines changed

‎README.md‎

Lines changed: 67 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,20 +25,31 @@ This firmware targets the Beepy hardware. It can still act as a USB keyboard, bu
2525

2626
Physical alt does not send an actual Alt key, but remaps the output scancodes to the range 135 to 161 in QWERTY order. This should be combined with a keymap for proper symbol output. This allows symbols to be customized without rebuilding the firmware, as well as proper use of the actual Alt key.
2727

28-
### The rest of the Readme
28+
## Quick Start
2929

30-
I have not yet updated any other part of the Readme file.
30+
git clone https://github.com/solderparty/i2c_puppet
31+
cd i2c_puppet
32+
./new-docker-build.sh
3133

32-
## Checkout
34+
## Checkout / Init Submodules
3335

34-
The code depends on the Raspberry Pi Pico SDK, which is added as a submodule. Because the Pico SDK includes TinyUSB as a module, it is not recommended to do a recursive submodule init, and rather follow these steps:
36+
This repository depends on the Raspberry Pi Pico SDK, which is added as a submodule.
37+
Because the Pico SDK includes TinyUSB as its own module,
38+
it is not recommended to do a recursive submodule init,
39+
and rather follow these steps:
3540

3641
git clone https://github.com/solderparty/i2c_puppet
3742
cd i2c_puppet
3843
git submodule update --init
3944
cd 3rdparty/pico-sdk
4045
git submodule update --init
4146

47+
Alternatively, feel free to invoke the `initialize-submodules.sh` script.
48+
49+
./initialize-submodules.sh
50+
51+
This script will perform the equivalent and inform you of the submodules current statuses.
52+
4253
## Build
4354

4455
See the `boards` directory for a list of available boards.
@@ -48,10 +59,59 @@ See the `boards` directory for a list of available boards.
4859
cmake -DPICO_BOARD=beepy -DCMAKE_BUILD_TYPE=Debug ..
4960
make
5061

51-
## Docker build
62+
## Docker Build
63+
64+
If you don't have the dependencies for building this project on your system,
65+
66+
you can also use a script that will run the build command using docker.
67+
68+
./new-docker-build.sh
69+
70+
The `new-docker-build.sh` script will invoke the commands from the `Build` section,
71+
72+
using the `djflix/rpi-pico-builder:latest` Docker image.
73+
74+
It will also ensure appropriate submodules have been at least initialized.
75+
76+
If any issues building, first try a "Clean Run" by deleting the `build` directory.
77+
78+
Due to how docker works, files in `build` may be owned by root and require `sudo` to delete.
79+
80+
To automatically trigger a "Clean Run",
81+
82+
sudo ./new-docker-build.sh clean
83+
84+
provide any argument to the `new-docker-build.sh` script while using `sudo`.
85+
86+
## Reset Submodules
87+
88+
If you need to reset the submodule state for some reason,
89+
feel free to invoke the `reset-submodules.sh` script.
90+
91+
./reset-submodules.sh
92+
93+
## Update Submodules
94+
95+
In general, one should avoid updating or changing anything inside the submodules.
96+
97+
Submodules should be changed in their respective origin repositories first.
98+
99+
Submodules of submodules cannot be updated from a superproject (parent of at least one submodule.)
100+
101+
If submodule updates are needed, it's recommend to:
102+
- ensure your code changes have landed in the appropriate origin repository branch.
103+
- if your code changes are to a submodule of a submodule,
104+
- ensure your code changes have propogated up to each superproject (parent of at least one submodule) in the chain.
105+
- make a separate branch in this repo just for submodule updates.
106+
- perform your submodule update for the direct submodule of this superproject (parent of at least one submodule):
107+
- <!-- this comment is to prevent automatic whitespace trimming -->
108+
```
109+
git submodule update --remote "3rdparty/pico-sdk"
110+
```
111+
112+
## The rest of the Readme
52113
53-
If you don't have the dependencies for building this project on your system you can also use a script that will run the build command using docker.
54-
The `dbuild.sh` script will invoke the commands from the `Build` section using the `djflix/rpi-pico-builder:latest` Docker image.
114+
The rest of the Readme file is effectively unchanged from upstream.
55115
56116
## Vendor USB Class
57117

‎dbuild.sh‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎initialize-submodules.sh‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#!/usr/bin/env bash
2+
3+
ORIGINAL_PWD=$(pwd) # Store the current working directory
4+
DIR="$(realpath "$( dirname "${BASH_SOURCE[0]}" )")"
5+
6+
get_submodule_status() {
7+
submodule_path="$1"
8+
submodule_status=$(git submodule status "${submodule_path}")
9+
10+
# Check the first character of the output to determine the status
11+
case "${submodule_status:0:1}" in
12+
'-')
13+
return 0
14+
;;
15+
' ')
16+
return 1
17+
;;
18+
'+')
19+
return 2
20+
;;
21+
*)
22+
return 3
23+
;;
24+
esac
25+
}
26+
27+
echo_submodule_status() {
28+
submodule_path="$1"
29+
status_code="$2"
30+
31+
case ${status_code} in
32+
0)
33+
echo "The submodule at ${submodule_path} is not initialized."
34+
;;
35+
1)
36+
echo "The submodule at ${submodule_path} is initialized and in-sync with superproject."
37+
;;
38+
2)
39+
echo "The submodule at ${submodule_path} is initialized and has changes."
40+
;;
41+
*)
42+
echo "Unknown status for the submodule at ${submodule_path}."
43+
;;
44+
esac
45+
}
46+
47+
submodule_status() {
48+
submodule_path="$1"
49+
get_submodule_status "${submodule_path}"
50+
status_code=$?
51+
echo_submodule_status "${submodule_path}" "${status_code}"
52+
return "${status_code}"
53+
}
54+
55+
initialize_submodule_if_not_initialized() {
56+
submodule_path="$1"
57+
original_pwd=$(pwd) # Store the current working directory
58+
59+
# Navigate to the submodule's directory
60+
cd "${submodule_path}" || return 1
61+
62+
# Run the submodule_status function to get the status
63+
submodule_status "${submodule_path}"
64+
status_code=$?
65+
66+
# If the status code is 0 (uninitialized), initialize the submodule
67+
if [[ ${status_code} -eq 0 ]]; then
68+
git submodule update --init
69+
echo "The submodule at ${submodule_path} has been initialized."
70+
fi
71+
72+
# Return to the original working directory
73+
cd "${original_pwd}" || return 1
74+
75+
return 0
76+
}
77+
78+
initialize_submodule_if_not_initialized "${DIR}"
79+
initialize_submodule_if_not_initialized "${DIR}/3rdparty/pico-sdk"
80+
81+
cd "${ORIGINAL_PWD}" || exit 1

‎new-docker-build.sh‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/usr/bin/env bash
2+
3+
ORIGINAL_PWD=$(pwd) # Store the current working directory
4+
DIR="$(realpath "$( dirname "${BASH_SOURCE[0]}" )")"
5+
6+
if [[ "${#}" -gt 0 ]]; then
7+
printf "%s\n" "Arguments passed to \`build-with-docker.sh\`."
8+
printf "%s\n" "\"Clean Run\" triggered."
9+
if [[ "${EUID}" -ne 0 ]]; then
10+
printf "%s\n" "Triggered behavior requires root access."
11+
printf "%s\n" "Please re-execute using \`sudo\` command."
12+
printf "%s\n" "Example: sudo !!"
13+
printf "%s\n" "Example: sudo $0 $@"
14+
exit 1
15+
fi
16+
printf "%s\n" "Executing: \`rm -rf \"${DIR}/build\"\`"
17+
rm -rf "${DIR}/build"
18+
printf "%s\n" "Build directory deleted for \"Clean Run\"."
19+
fi
20+
21+
"${DIR}/initialize-submodules.sh"
22+
23+
docker run --rm -it \
24+
-v "${DIR}/3rdparty/pico-sdk:/pico-sdk" \
25+
-v "${DIR}:/project" \
26+
djflix/rpi-pico-builder:latest \
27+
bash -c 'mkdir -p build && cd build && cmake -DPICO_BOARD=beepy .. && make clean && make'
28+
29+
cd "${ORIGINAL_PWD}" || exit 1
30+
31+
# DOCKER IMAGE DETAILS:
32+
# https://github.com/DJFliX/rpi-pico-builder (fork of original, smaller size, newer ubuntu version, available on docker hub)
33+
# https://github.com/xingrz/rpi-pico-builder (original, public archive repo, available on docker hub)
34+
#
35+
# Here is the entire Dockerfile as of 2023-08-25:
36+
#
37+
# BEGIN of DJFliX/rpi-pico-builder Dockerfile
38+
# FROM ubuntu:22.04
39+
#
40+
# ENV DEBIAN_FRONTEND=noninteractive
41+
# RUN apt-get update
42+
# RUN apt-get install -y build-essential
43+
# RUN apt-get install -y python3
44+
# RUN apt-get install -y cmake
45+
# RUN apt-get install -y gcc-arm-none-eabi libnewlib-arm-none-eabi \
46+
# && rm -rf /usr/lib/arm-none-eabi/newlib/thumb/v8* \
47+
# /usr/lib/arm-none-eabi/newlib/thumb/v7e* \
48+
# /usr/lib/arm-none-eabi/newlib/thumb/v7ve+simd \
49+
# /usr/lib/arm-none-eabi/newlib/thumb/v7-a* \
50+
# /usr/lib/arm-none-eabi/newlib/thumb/v7-r+fp.sp \
51+
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v7e* \
52+
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v7-a* \
53+
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v7+fp* \
54+
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v8*
55+
#
56+
# VOLUME [ "/pico-sdk", "/project" ]
57+
#
58+
# ENV PICO_SDK_PATH=/pico-sdk
59+
#
60+
# WORKDIR /project
61+
# END of DJFliX/rpi-pico-builder Dockerfile
62+
#

‎reset-submodules.sh‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/usr/bin/env bash
2+
3+
ORIGINAL_PWD=$(pwd) # Store the current working directory
4+
DIR="$(realpath "$( dirname "${BASH_SOURCE[0]}" )")"
5+
6+
cd "${DIR}" || exit 1
7+
8+
git submodule foreach git submodule foreach git submodule foreach git reset --hard
9+
git submodule foreach git submodule foreach git reset --hard
10+
git submodule foreach git reset --hard
11+
12+
git submodule update -- "3rdparty/pico-sdk"
13+
14+
cd "3rdparty/pico-sdk" || exit 1
15+
16+
git submodule update -- "lib/tinyusb"
17+
18+
cd "${ORIGINAL_PWD}" || exit 1

0 commit comments

Comments
 (0)