IOTHUB SOFTWARE · 04

Python IoT 보조서버 준비

Python은 ESP 보드에 직접 올라가는 코드가 아니라, 장치와 서버, 알림, AI 처리 사이를 이어주는 보조 서버 역할로 사용합니다.

핵심 용어Pythonpip터미널PATH

ESP32와 AI를 연결하는 중간 서버는 Python으로 구성하는 경우가 많습니다. Python은 문법이 비교적 읽기 쉬운 프로그래밍 언어이며, 이 글에서는 설치와 기본 실행 흐름만 다룹니다.

다운로드

python.org/downloads 접속. 노란색 Download Python 3.x.x 버튼을 누른다. 최신 버전이면 충분하다 (3.8 이상).

Windows 설치

다운로드한 .exe 파일 실행.
⚠ 제일 중요한 단계: 첫 화면 하단의 Add Python to PATH 체크박스를 반드시 체크! 이 항목을 체크하지 않으면 나중에 터미널에서 Python 명령을 찾지 못할 수 있습니다.
Install Now 클릭. 보통 2분 정도면 설치가 끝납니다.
설치 확인: 키보드에서 Windows 키 + R → cmd 입력 → 검은 창이 뜨면 python --version 입력.
Python 3.x.x가 출력되면 성공.

Mac 설치

다운로드한 .pkg 파일 실행.
Continue → Install.
설치 확인: Command + Space → Terminal 입력 → 검은 창이 뜨면 python3 --version 입력.
Python 3.x.x 출력되면 성공.

Mac은 기본 Python 2.7이 깔려 있어서 python이 아니라 python3으로 써야 한다. 이 시리즈의 모든 명령어도 맥에서는 python3으로 읽으면 된다.

pip이란?

pip은 "Python 패키지를 설치하는 도구"입니다. 앱스토어처럼 필요한 패키지를 내려받는 역할이며, Python을 설치하면 보통 함께 설치됩니다.

터미널(검은 창)에서 이렇게 쓴다:

code

pip install 패키지이름

예: pip install flask → Flask라는 웹 서버 패키지를 설치한다. 23~24편에서 쓴다.

설치 확인: pip --version 입력 → 버전이 나오면 OK.

터미널(검은 창)이란 무엇인가요?

Windows: Windows 키 누르고 cmd 입력 → 명령 프롬프트 클릭. 검은 창이 뜬다.
Mac: Command + Space → Terminal 입력 → 검은 창이 뜬다.

이 검은 창에 명령어를 입력해 프로그램을 실행합니다. 마우스로 클릭하는 대신 키보드로 명령을 입력한다고 이해하면 됩니다. 이 글에서 사용할 명령어는 세 개뿐입니다.

code

python --version     ← Python 잘 깔렸나 확인
pip install flask    ← 필요한 패키지 설치
python server.py     ← 서버 실행

설치 확인 체크리스트

□ 터미널 열 수 있음
□ python --version (맥은 python3 --version) → Python 3.x.x 출력
□ pip --version → 버전 출력

안 될 때

증상	해결
`python` 명령어를 못 찾음	Windows: 설치 시 `Add to PATH`를 체크했는지 확인합니다. 체크하지 않았다면 Python을 다시 설치합니다.
`pip` 명령어를 못 찾음	`python -m pip --version`으로 대신 실행합니다.
Mac에서 `python3`를 사용해야 하는 경우	Mac 기본 설정입니다. 시리즈 명령어를 `python3`으로 바꿔서 입력합니다.
"Microsoft Store"가 뜸 (Windows)	`시작` → `앱 실행 별칭 관리`에서 `python` 관련 항목을 끕니다. 그다음 터미널을 다시 시작합니다.

Python은 장치 코드가 아니라 운영 코드다

ESP32 안에 들어가는 펌웨어는 센서를 읽고 네트워크로 값을 보내는 역할에 집중하는 편이 좋습니다. 반대로 Python은 여러 장치의 상태를 모으고, MQTT 메시지를 해석하고, 텔레그램 알림을 보내고, AI 처리나 로그 저장을 담당하는 운영 코드에 가깝습니다. 역할을 나누면 보드 코드가 단순해지고 서버 기능을 바꾸기도 쉬워집니다.

처음부터 로그를 남긴다

Python 보조서버는 화면 없이 백그라운드에서 도는 경우가 많습니다. 그래서 시작할 때 설정 파일 경로, 포트, MQTT 브로커 주소, 텔레그램 토큰 로딩 여부를 로그로 남겨야 합니다. 장애가 생겼을 때 “실행은 됐는데 왜 아무 알림도 안 오지?” 같은 상황을 줄일 수 있습니다.

시작 로그: 설정 파일, 실행 포트, 사용 환경.
연결 로그: MQTT 연결 성공/실패, 재연결 횟수.
처리 로그: 들어온 topic, 파싱 실패, 알림 전송 결과.
오류 로그: traceback과 마지막 원인 줄.

IoT에서 Python을 쓰는 현실적인 이유

ESP32가 센서값을 읽고 MQTT로 보내는 일은 잘하지만, 여러 장치의 상태를 모으고, AI에게 질문하고, 텔레그램 알림을 보내고, 로그를 정리하는 일은 Python 쪽이 훨씬 편합니다. 그래서 작은 IoT 시스템에서도 보드 코드와 서버 코드를 분리하면 유지보수가 쉬워집니다.

venv를 쓰는 이유

Python 패키지를 전역으로 막 설치하면 나중에 프로젝트끼리 버전이 꼬입니다. 가상환경을 쓰면 프로젝트마다 필요한 패키지 버전을 따로 둘 수 있습니다. 작은 실험이라도 venv를 쓰는 습관을 들이면 서버 이전이나 복구가 쉬워집니다.

command

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

실행 확인 기준

python --version이 예상 버전으로 나온다.
pip --version이 같은 venv 경로를 가리킨다.
서버 실행 시 포트, 토큰, 설정 파일 경로가 로그에 나온다.
오류가 발생했을 때 traceback 첫 줄만 보지 말고 마지막 원인 줄을 확인합니다.