Skip to content

Commit

Permalink
Improve Scripts & Docs
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
dezren39 committed Aug 25, 2023
1 parent c1c9b23 commit 5435651
Show file tree
Hide file tree
Showing 5 changed files with 223 additions and 15 deletions.
74 changes: 67 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,20 +25,31 @@ This firmware targets the Beepy hardware. It can still act as a USB keyboard, bu

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.

### The rest of the Readme
## Quick Start

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

## Checkout
## Checkout / Init Submodules

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:
This repository depends on the Raspberry Pi Pico SDK, which is added as a submodule.
Because the Pico SDK includes TinyUSB as its own module,
it is not recommended to do a recursive submodule init,
and rather follow these steps:

git clone https://github.com/solderparty/i2c_puppet
cd i2c_puppet
git submodule update --init
cd 3rdparty/pico-sdk
git submodule update --init

Alternatively, feel free to invoke the `initialize-submodules.sh` script.

./initialize-submodules.sh

This script will perform the equivalent and inform you of the submodules current statuses.

## Build

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

## Docker build
## Docker Build

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.

./new-docker-build.sh

The `new-docker-build.sh` script will invoke the commands from the `Build` section,

using the `djflix/rpi-pico-builder:latest` Docker image.

It will also ensure appropriate submodules have been at least initialized.

If any issues building, first try a "Clean Run" by deleting the `build` directory.

Due to how docker works, files in `build` may be owned by root and require `sudo` to delete.

To automatically trigger a "Clean Run",

sudo ./new-docker-build.sh clean

provide any argument to the `new-docker-build.sh` script while using `sudo`.

## Reset Submodules

If you need to reset the submodule state for some reason,
feel free to invoke the `reset-submodules.sh` script.

./reset-submodules.sh

## Update Submodules

In general, one should avoid updating or changing anything inside the submodules.

Submodules should be changed in their respective origin repositories first.

Submodules of submodules cannot be updated from a superproject (parent of at least one submodule.)

If submodule updates are needed, it's recommend to:
- ensure your code changes have landed in the appropriate origin repository branch.
- if your code changes are to a submodule of a submodule,
- ensure your code changes have propogated up to each superproject (parent of at least one submodule) in the chain.
- make a separate branch in this repo just for submodule updates.
- perform your submodule update for the direct submodule of this superproject (parent of at least one submodule):
- <!-- this comment is to prevent automatic whitespace trimming -->
```
git submodule update --remote "3rdparty/pico-sdk"
```
## The rest of the Readme
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.
The `dbuild.sh` script will invoke the commands from the `Build` section using the `djflix/rpi-pico-builder:latest` Docker image.
The rest of the Readme file is effectively unchanged from upstream.
## Vendor USB Class
Expand Down
8 changes: 0 additions & 8 deletions dbuild.sh

This file was deleted.

81 changes: 81 additions & 0 deletions initialize-submodules.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
#!/usr/bin/env bash

ORIGINAL_PWD=$(pwd) # Store the current working directory
DIR="$(realpath "$( dirname "${BASH_SOURCE[0]}" )")"

get_submodule_status() {
submodule_path="$1"
submodule_status=$(git submodule status "${submodule_path}")

# Check the first character of the output to determine the status
case "${submodule_status:0:1}" in
'-')
return 0
;;
' ')
return 1
;;
'+')
return 2
;;
*)
return 3
;;
esac
}

echo_submodule_status() {
submodule_path="$1"
status_code="$2"

case ${status_code} in
0)
echo "The submodule at ${submodule_path} is not initialized."
;;
1)
echo "The submodule at ${submodule_path} is initialized and in-sync with superproject."
;;
2)
echo "The submodule at ${submodule_path} is initialized and has changes."
;;
*)
echo "Unknown status for the submodule at ${submodule_path}."
;;
esac
}

submodule_status() {
submodule_path="$1"
get_submodule_status "${submodule_path}"
status_code=$?
echo_submodule_status "${submodule_path}" "${status_code}"
return "${status_code}"
}

initialize_submodule_if_not_initialized() {
submodule_path="$1"
original_pwd=$(pwd) # Store the current working directory

# Navigate to the submodule's directory
cd "${submodule_path}" || return 1

# Run the submodule_status function to get the status
submodule_status "${submodule_path}"
status_code=$?

# If the status code is 0 (uninitialized), initialize the submodule
if [[ ${status_code} -eq 0 ]]; then
git submodule update --init
echo "The submodule at ${submodule_path} has been initialized."
fi

# Return to the original working directory
cd "${original_pwd}" || return 1

return 0
}

initialize_submodule_if_not_initialized "${DIR}"
initialize_submodule_if_not_initialized "${DIR}/3rdparty/pico-sdk"

cd "${ORIGINAL_PWD}" || exit 1
62 changes: 62 additions & 0 deletions new-docker-build.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
#!/usr/bin/env bash

ORIGINAL_PWD=$(pwd) # Store the current working directory
DIR="$(realpath "$( dirname "${BASH_SOURCE[0]}" )")"

if [[ "${#}" -gt 0 ]]; then
printf "%s\n" "Arguments passed to \`build-with-docker.sh\`."
printf "%s\n" "\"Clean Run\" triggered."
if [[ "${EUID}" -ne 0 ]]; then
printf "%s\n" "Triggered behavior requires root access."
printf "%s\n" "Please re-execute using \`sudo\` command."
printf "%s\n" "Example: sudo !!"
printf "%s\n" "Example: sudo $0 $@"
exit 1
fi
printf "%s\n" "Executing: \`rm -rf \"${DIR}/build\"\`"
rm -rf "${DIR}/build"
printf "%s\n" "Build directory deleted for \"Clean Run\"."
fi

"${DIR}/initialize-submodules.sh"

docker run --rm -it \
-v "${DIR}/3rdparty/pico-sdk:/pico-sdk" \
-v "${DIR}:/project" \
djflix/rpi-pico-builder:latest \
bash -c 'mkdir -p build && cd build && cmake -DPICO_BOARD=beepy .. && make clean && make'

cd "${ORIGINAL_PWD}" || exit 1

# DOCKER IMAGE DETAILS:
# https://github.com/DJFliX/rpi-pico-builder (fork of original, smaller size, newer ubuntu version, available on docker hub)
# https://github.com/xingrz/rpi-pico-builder (original, public archive repo, available on docker hub)
#
# Here is the entire Dockerfile as of 2023-08-25:
#
# BEGIN of DJFliX/rpi-pico-builder Dockerfile
# FROM ubuntu:22.04
#
# ENV DEBIAN_FRONTEND=noninteractive
# RUN apt-get update
# RUN apt-get install -y build-essential
# RUN apt-get install -y python3
# RUN apt-get install -y cmake
# RUN apt-get install -y gcc-arm-none-eabi libnewlib-arm-none-eabi \
# && rm -rf /usr/lib/arm-none-eabi/newlib/thumb/v8* \
# /usr/lib/arm-none-eabi/newlib/thumb/v7e* \
# /usr/lib/arm-none-eabi/newlib/thumb/v7ve+simd \
# /usr/lib/arm-none-eabi/newlib/thumb/v7-a* \
# /usr/lib/arm-none-eabi/newlib/thumb/v7-r+fp.sp \
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v7e* \
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v7-a* \
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v7+fp* \
# /usr/lib/gcc/arm-none-eabi/10.3.1/thumb/v8*
#
# VOLUME [ "/pico-sdk", "/project" ]
#
# ENV PICO_SDK_PATH=/pico-sdk
#
# WORKDIR /project
# END of DJFliX/rpi-pico-builder Dockerfile
#
13 changes: 13 additions & 0 deletions reset-submodules.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
#!/usr/bin/env bash

ORIGINAL_PWD=$(pwd) # Store the current working directory
DIR="$(realpath "$( dirname "${BASH_SOURCE[0]}" )")"

cd "${DIR}" || exit 1

git submodule foreach git submodule foreach git submodule foreach git reset --hard
git submodule foreach git submodule foreach git reset --hard
git submodule foreach git reset --hard
git submodule update --recursive

cd "${ORIGINAL_PWD}" || exit 1

0 comments on commit 5435651

Please sign in to comment.