nsumo_video - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #typescript #llm #golang #go #android #docker #windows #kubernetes #vue #mcp

nsumo_video

(★ 187)

A microcontroller-based embedded project written from scratch in a video series on YouTube.

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
- coding_guidelines.md
- nsumo.jpg
- retreat_state.png
- retreat_state.uml
- schematic.png
- state_machine.png
- state_machine.uml
- sw_arch.png
- sysdiag.jpg
- printf
- printf_config.h
- - drive.c
  - drive.h
  - enemy.c
  - enemy.h
  - input_history.c
  - input_history.h
  - line.c
  - line.h
  - state_attack.c
  - state_attack.h
  - state_common.h
  - state_machine.c
  - state_machine.h
  - state_manual.c
  - state_manual.h
  - state_retreat.c
  - state_retreat.h
  - state_search.c
  - state_search.h
  - state_wait.c
  - state_wait.h
  - timer.c
  - timer.h
- - assert_handler.c
  - assert_handler.h
  - defines.h
  - enum_to_string.c
  - enum_to_string.h
  - ring_buffer.c
  - ring_buffer.h
  - sleep.c
  - sleep.h
  - trace.c
  - trace.h
- - adc.c
  - adc.h
  - i2c.c
  - i2c.h
  - io.c
  - io.h
  - ir_remote.c
  - ir_remote.h
  - led.c
  - led.h
  - mcu_init.c
  - mcu_init.h
  - millis.c
  - millis.h
  - pwm.c
  - pwm.h
  - qre1113.c
  - qre1113.h
  - tb6612fng.c
  - tb6612fng.h
  - uart.c
  - uart.h
  - vl53l0x.c
  - vl53l0x.h
- - test.c
- main.c
- build_tests.sh
- dockerfile
.clang-format
.gitignore
.gitmodules
LICENSE
Makefile
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/artfulbytes/nsumo_video

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd nsumo_video

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

them from being merged until they pass. The action runs inside a docker container, which has the

이 명령어를 터미널에 그대로 입력해 실행하세요.

required cross-toolchain installed. The dockerfile is located under **tools/**, and the docker image is

이 명령어를 터미널에 그대로 입력해 실행하세요.

available in a [repository at Docker Hub](https://hub.docker.com/r/artfulbytes/msp430-gcc-9.3.1.11).

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Make

보통

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Make Linux/macOS는 보통 기본 설치되어 있습니다. Windows는 별도 설치(예: MSYS2, WSL)가 필요합니다.

make

생성된 빌드 설정을 바탕으로 실제 컴파일을 진행해 실행 파일을 만듭니다.

✅ 에러 없이 끝나면 성공입니다. 생성된 실행 파일을 직접 실행해보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Nsumo
This repository tracks the code of Nsumo (500g 10x10cm Sumobot) as I re-write it
from scratch and show the complete process in a [YouTube series](https://www.youtube.com/watch?v=g9KbXJydf8I&t=1s).
You find the hardware design [here](https://github.com/artfulbytes/nsumo_hardware.git).
The project is meant to serve as an educational example and case study of a
microcontroller-based embedded project.

<img src="/docs/nsumo.jpg">

## Directory structure
The directory structure is based on the
[pitchfork layout](https://github.com/vector-of-bool/pitchfork), and I describe it
more in [this video](https://www.youtube.com/watch?v=6oJ2LLxfP3s).

| Directory    | Description                                                  |
|--------------|--------------------------------------------------------------|
| build/       | Build output (object files + executable)                     |
| docs/        | Documentation (e.g., coding guidelines, images)              |
| src/         | Source files (.c/.h)                                         |
| src/app/     | Source files for the application layer (see SW architecture) |
| src/common/  | Source files for code used across the project                |
| src/drivers/ | Source files for the driver layer (see SW architecture)      |
| src/test/    | Source files related to test code                            |
| external/    | External dependencies (as git submodules if possible)        |
| tools/       | Scripts, configs, binaries                                   |
| .github/     | Configuration file for GitHub actions                        |

## Build
The two most common ways to build code for a microcontroller are from
an IDE (often supplied by the vendor) or from the command-line through a build
system (for example, make). There are pros and cons to both ways, and I describe
them in [this video](https://www.youtube.com/watch?v=H1HToCzku9Y) and
[this video](https://www.youtube.com/watch?v=HCfq44NNBaU).

In short, using an IDE is the most straightforward approach, but
at the same time less flexible because it forces you into a particular environment.
A build system is more complicated to set up, but it can be combined with your editor
of choice, gives more control over the build process, is great for automation (see CI),
and allows for a command-line based environment, which transfers better across projects.
This project can be built both ways, however, _make_ is the preferred way, but the IDE
is helpful when step-debugging the code.

## make (Makefile)
The code targets the MSP430G2553 and must be built with a cross-toolchain. While
there are several toolchains for this microcontroller, msp430-gcc is the one used in this project,
which is available on [TI's website](https://www.ti.com/tool/MSP430-GCC-OPENSOURCE).
Watch [this video](https://www.youtube.com/watch?v=HCfq44NNBaU) and
[this video](https://www.youtube.com/watch?v=dh1NFAIoZCI) for more details.

There is a _Makefile_ to build the code with _make_ from the command-line:
``` Bash
TOOLS_PATH=<INSERT TOOLS PATH> make HW=<INSERT TARGET>
```

The path to the toolchain must be specified with the environment variable _TOOLS_PATH_.

The argument _HW_ specifies which hardware to target, either _NSUMO_
(Robot with 28-pin msp430g2553) or _LAUNCHPAD_ (evaluation board with 20-pin
msp430g2553).

For example, if the toolchain is available at _/home/artfulbytes/dev/tools/msp430-gcc_,
and targeting the evaluation board:

```
TOOLS_PATH=$HOME/dev/tools make HW=LAUNCHPAD
```

## IDE
The IDE provided by the vendor (TI) for the MSP430 family of microcontrollers is
called Code Composer Studio (CCSSTUDIO). It's an eclipse-based IDE, and is available
at [TI's website](https://www.ti.com/tool/CCSTUDIO). The below steps have
been verified to work with version CCSTUDIO 11.1 and MSP430-GCC 9.3.1.11.

1. Install CCSTUDIO and MSP430-GCC, and make sure the GCC compiler can be selected
   from inside CCSTUDIO.
2. Create a new CCS project
    - Target: MSP430G2553
    - Compiler version: GNU v9.3.1.11
    - Empty project (no main file)
3. Drag the src/ folder into the project explorer and link to files and
   folders
4. Under properties
    - Add src/ directory to include paths
    - Add define symbols (see Makefile), e.g. LAUNCHPAD

## Tests
There are no unit tests, but there are test functions inside src/test/test.c, which
are written to test isolated parts of the code. They run on target but are not built
as part of the normal build. Only one test function can be built at a time, and it's
built as follows (test_assert as an example):

``` C
make TARGET=LAUNCHPAD TEST=test_assert
```

## Pushing a new change
These are the typical steps taken for each change.

1. Create a local branch
2. Make the code changes
3. Build the code
4. Flash and test the code on the target
5. Static analyse the code
6. Format the code
7. Commit the code
8. Push the branch to GitHub
9. Open a pull-request
10. Merge the pull request (must pass CI first)

This workflow is described further in [this video](https://www.youtube.com/watch?v=dh1NFAIoZCI).

## Commit message
Commit messages should follow the specification laid out by
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). See
[this video](https://www.youtube.com/watch?v=TFhbv6gw2Wo) for more details.

## Continuous Integration (CI)
There is simple continuous integration (CI)
system in place to have some form of protection against breaking code changes. This system is realized
through GitHub actions and is configured in **ci.yml** located under
**.github/workflows**. The action builds and analyses (cppcheck) each commit pushed to GitHub and blocks
them from being merged until they pass. The action runs inside a docker container, which has the
required cross-toolchain installed. The dockerfile is located under **tools/**, and the docker image is
available in a [repository at Docker Hub](https://hub.docker.com/r/artfulbytes/msp430-gcc-9.3.1.11).
The CI system is described in detail in [this video](https://www.youtube.com/watch?v=dh1NFAIoZCI).

Note, the CI system provides weak protection against breaking code changes since it only builds and
static analyses the code. It's mainly there to demonstrate the principle. A more rigorous CI system
(professional environment) would unit-test the code and test it on the real target.

## Code formatter
The codebase follows certain formatting rules, which are enforced by the code formatter
**clang-format**. These rules are specified in the **.clang-format** located in the root
directory. There is a rule in the **Makefile** to format all source files with one command
(requires clang-format to be installed).

``` Bash
make format
```

Sometimes it's desirable to ignore these formatting rules, and this can be achieved with special comments.

``` C
// clang-format off
typedef enum {
    IO_10, IO_11, IO_12, IO_13, IO_14, IO_15, IO_16, IO_17,
    IO_20, IO_21, IO_22, IO_23, IO_24, IO_25, IO_26, IO_27,
    IO_30, IO_31, IO_32, IO_33, IO_34, IO_35, IO_36, IO_37,
} io_generic_e;
// clang-format on
```

## Coding guidelines
Apart from the basic formatting rules, the codebase also follows certain coding guidelines.
These are described in **docs/coding_guidelines.md**.

## Static analysis
To catch coding mistakes early on (in addition to the ones the compiler catches), I use a static
analyzer, **cppcheck**. There is a rule in the **Makefile** to analyse all files with **cppcheck**.

``` Bash
make cppcheck
```

I explain it more in [this video](https://www.artfulbytes.com/analysis-with-cppcheck).

## Memory footprint analysis
The memory footprint on a microcontroller is very limited. The MSP430G2553 only has
16 KB (16 000 bytes) of read-only memory (ROM) or flash memory. This means one has to
be conscious of how much space each code snippet takes, which is one of the challenges
with microcontroller programming. For this reason, it's useful to have tools in place
to analyse the space occupied. There are two such programs available in the toolchain
(_readelf_ and _objdump_), and two corresponding rules in the _Makefile_.

One rule to see how much total space is occupied,
```
make size
```
and another rule to see how much space is occupied by individual symbols (functions + variables):
```
make symbols
```
which is useful to track down the worst offenders.

## Assert
Several things happen when an assert occurs to make it easy to detect and localize.
First it triggers a breakpoint (if a debugger is attached), then it traces the address
of the assert, and finally it endlessly blinks an LED. The address printed, is the
program counter, and _addr2line can be used to retrieve the file and line number,
and there is a makefile rule for it. For example, if an assert triggered at address
0x1234, you can run

```
make HW=LAUNCHPAD addr2line ADDR=0x1234
```

## Diagrams
There are some PlantUML diagrams under _docs/_. The plaintext can be converted into
a viewable image with

```
java -jar plantuml.jar diagram.uml
```

Download plantuml.jar from [PlantUML website](https://plantuml.com/), and install
dependencies (on Ubuntu) with

```
sudo apt install default-jre
sudo apt install graphviz
```

## Schematic
<img src="/docs/schematic.png">

## Software architecture
<img src="/docs/sw_arch.png">

## Block diagram
<img src="/docs/sysdiag.jpg">

## State machine
<img src="/docs/state_machine.png">
<img src="/docs/retreat_state.png">