در این فصل چه میسازی#
هر سفری دو چیز میخواهد: زبانِ آن سرزمین، و کلیدِ درهایش. فصلِ بعد پروژهٔ تو برای اولین بار با یک هوش مصنوعیِ واقعی حرف میزند — و امروز هر دو چیزِ لازم برای این سفر را برمیداری. اول زبان: سرویسهای بزرگِ اینترنت، از هواشناسی تا Gemini، همه به یک زبانِ مشترک جواب میدهند به اسم JSON (راستش را بخواهی، فصل ۲ که زمانِ جهانی را گرفتی، آن متنِ پر از آکولاد و دونقطه JSON بود!). دوم کلید: درِ سرویسهای بزرگ با یک رمزِ شخصی به اسم API key باز میشود — و رمز، جای امن میخواهد. آخرِ فصل، خانهٔ امنی به اسم secrets.py میسازی و بالاخره پسوردِ WiFi را از وسطِ کد جمع میکنی. و پروژهٔ امروز بامزه است: ایستگاه هواشناسیِ ترم ۲ که دمای اتاقت را میگفت، امروز جهانی میشود — دمای همین لحظهٔ توکیو، روی OLED روی میزِ تو!
آخر این فصل میتوانی:
- دیکشنری کامل بسازی و بخوانی: خواندن با کلید، تغییرِ مقدار، افزودنِ کلید، و ساختارِ تودرتو (دیکشنری در دیکشنری، لیست در دیکشنری).
- با
json.dumpsوjson.loadsبین رشته و دیکشنری رفتوبرگشت کنی و قواعدِ سختگیرانهٔ JSON را بگویی. - پاسخِ JSON یک سرویسِ واقعی را با کلیدزنیِ تودرتو بخوانی و روی OLED نشان بدهی.
- بگویی API key چیست (مثلِ رمزِ عبور) و rate limit یعنی چه.
- فایلِ
secrets.pyبسازی و توضیح بدهی چرا رمزها هرگز در کدِ اشتراکی نمیمانند.
قبل از شروع: چکلیست پیشنیاز#
قبل از ادامه اینها را چک کن — اگر یکیشان لنگ میزند، اول برگرد همان فصل:
- از فصل ۲: ماژول
urequests، درخواستِ GET و خواندنِ مقدار باdata["key"]— امروز دیکشنری را کامل میکنیم. - از فصل ۱: اتصال WiFi — و ادای قولِ همان فصل: پسورد به خانهٔ امن میرود.
- از فصل ۳: رشتهٔ سهنقلقولی — برای JSONهای دستسازِ تمرینی.
- از ترم ۳، فصل ۳: ساخت و
importماژولِ خودمان (robot.py) —secrets.pyهم دقیقاً همینطور کار میکند. - از ترم ۲، فصل ۵ و ۷: لیست و index + نمایشگر OLED با کتابخانهٔ
ssd1306.
لوازم این فصل:
| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ESP32 + Breadboard + کابل USB | ۱ | — |
| OLED 0.96 اینچ I2C (کیت ترم ۲) | ۱ | بدونِ OLED هم میشود — خروجی در Shell |
| WiFi خانگی ۲.۴ گیگاهرتز | — | هاتاسپاتِ گوشی |
| کامپیوتر با Thonny و کابل USB | ۱ | — |
۱. دیکشنری: قفسهای با کشوهای اسمدار#
از ترم ۲ لیست را داری: یک قفسه با کشوهای شمارهدار — notes[0]، notes[1]. لیست عالی است وقتی ترتیب مهم است. ولی فرض کن میخواهی مشخصاتِ رباتت را نگه داری: اسم، سرعت، رنگ. «اسم» که شماره ندارد! اینجا دیکشنری میآید: قفسهای با کشوهای اسمدار. روی هر کشو یک برچسب — به برچسب میگوییم کلید (key) و به محتوای کشو مقدار (value). فصل ۲ فقط یاد گرفتی کشو را باز کنی (data["key"])؛ امروز کلِ قفسه مالِ توست. Shell را باز کن و با من بساز:
>>> me = {"name": "AIRO", "speed": 600, "online": True}
>>> me["name"]
'AIRO'
>>> me["speed"] = 650 # avaz kardan-e meghdar-e yek keshoo
>>> me["color"] = "abi" # keshoo-ye jadid ba yek khat!
>>> me
{'name': 'AIRO', 'speed': 650, 'online': True, 'color': 'abi'}
قواعدش را ببین: آکولادِ باز، جفتهای «کلید دونقطه مقدار» با کاما، آکولادِ بسته. خواندن و نوشتن، هر دو با ["کلید"] — اگر کلید باشد مقدارش عوض میشود، نباشد ساخته میشود.
💡 نکته: ممکن است کشوها روی بردِ تو با ترتیبِ دیگری چاپ شوند. اشکالی ندارد و برد خراب نیست: لیست ترتیب دارد، دیکشنری ندارد. در دیکشنری فقط برچسبها مهماند، نه اینکه کدام اول نوشته شده — پس هیچوقت به ترتیبِ کشوها تکیه نکن.
✅ چک کن: با print(me) قفسهات را ببین. باید چهار کشو داشته باشد: name، speed (که حالا ۶۵۰ است)، online و کشوی تازهٔ color.
۲. ساختارِ تودرتو: قفسه در قفسه#
مقدارِ یک کشو هر چیزی میتواند باشد: رشته، عدد، بولی — و حتی یک دیکشنریِ دیگر! اینجاست که قدرتِ واقعی معلوم میشود:
>>> robot_info = {
... "name": "AIRO",
... "battery": {"volt": 7.4, "percent": 80},
... "sensors": ["DHT11", "LDR", "HC-SR04"],
... }
>>> robot_info["battery"]["percent"]
80
>>> robot_info["sensors"][0]
'DHT11'
به این میگوییم ساختارِ تودرتو (nested): داخلِ کشوی battery یک قفسهٔ کوچکتر است! برای رسیدن به درصدِ شارژ، دو بار کشو باز میکنیم: اول ["battery"]، بعد ["percent"] — از چپ به راست، لایهبهلایه. و کشوی sensors یک لیست دارد؛ پس اول با کلید بازش میکنیم، بعد با index شمارهدارِ ترم ۲: [0].

ترکیبِ دیکشنری و لیست، اسکلتِ تقریباً همهٔ دادههای اینترنت است — و پاسخِ Gemini در فصل ۷ هم دقیقاً همین شکلی است.
چالش: چطور به "LDR" برسی؟
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
۳. ماژول json: مترجمِ دوطرفه#
دیکشنری مالِ Python است و داخلِ حافظهٔ برد زندگی میکند. ولی وقتی داده میخواهد سفر کند — از سرویسِ هواشناسی به بردِ تو، یا از بردِ تو به Gemini — باید تبدیل به متن شود، چون شبکه فقط متن جابهجا میکند. JSON دقیقاً همین است: «دیکشنریِ متنشده» با قواعدِ جهانی، تا هر زبانِ برنامهنویسی در هر گوشهٔ دنیا بفهمدش. MicroPython یک مترجمِ رسمی دارد: ماژولِ json با دو فعلِ مهم. dumps یعنی «دیکشنری را بریز بیرون به شکلِ رشته» و loads یعنی «رشته را بار کن به شکلِ دیکشنری»:
>>> import json
>>> text = json.dumps(me)
>>> text
'{"name": "AIRO", "speed": 650, "online": true, "color": "abi"}'
دو چیزِ عجیب میبینی؟ اول اینکه همهٔ کوتیشنها دابل شدند، و دوم Trueی بزرگِ Python شده trueی کوچک! اینها قواعدِ JSON هستند، نه سلیقه: در JSON کوتیشن فقط دابل است و true/false کوچک نوشته میشوند. حالا برای برگشت، مترجم را برعکس صدا میزنیم — و بگذار عمداً یک اشتباهِ رایج هم بکنیم: JSON دستساز را با کوتیشنِ تکی بنویسیم، همانطور که در Python عادت داریم:
>>> data = json.loads("{'temp': 24, 'hum': 41}")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: syntax error in JSON
ValueError: syntax error in JSON — این خطا را خوب به خاطر بسپار، چون در دنیای API زیاد میبینیاش. مترجمِ JSON سختگیر است: کوتیشنِ تکی؟ رد. متنی که اصلاً JSON نیست (مثلاً صفحهٔ خطای HTML)؟ رد. کامای اضافه در انتها هم در JSON غلط است و Python کامپیوتر ردش میکند، ولی json روی برد از آن میگذرد؛ پس هرگز به این چشمپوشی تکیه نکن. اصلاحش کن — کوتیشنها را دابل بگذار:
>>> data = json.loads('{"temp": 24, "hum": 41}')
>>> data["temp"] + 1
25
ببین چه شد: تا یک لحظه پیش "24" وسطِ یک متنِ مرده بود؛ الان data["temp"] یک عددِ زنده است که میشود با آن حساب کرد. این جادوی loads است. و یک اتصالِ قشنگ به گذشته: r.json() که از فصل ۲ استفاده میکنی، دقیقاً همین json.loads است که urequests از سرِ لطف خودش برایت صدا میزند! کدِ کاملِ زمین بازیِ امروز — دیکشنری و json کنارِ هم — در 01_json_playground.py است:
# Term 4 - Session 06 - zamin-e bazi: dictionary-e kamel + module-ye json
import json
# --- 1) sakht-e dictionary: shenasname-ye robot-e ma ---
me = {"name": "AIRO", "speed": 600, "online": True}
print(me["name"]) # khandan ba kelid
me["speed"] = 650 # avaz kardan-e meghdar
me["color"] = "abi" # keshoo-ye jadid ba yek khat
print(me)
# --- 2) dumps: dictionary -> reshte-ye JSON (baraye ferestadan) ---
text = json.dumps(me)
print(text) # deghat: quote-ha double shodand, True shod true!
# --- 3) loads: reshte-ye JSON -> dictionary (baraye fahmidan) ---
data = json.loads('{"temp": 24, "hum": 41}')
print(data["temp"] + 1) # alan adad-e zende ast: 25
# --- 4) sakhtar-e tu-dar-tu: dictionary dar dictionary + list dar dictionary ---
robot_json = """{
"name": "AIRO",
"battery": {"volt": 7.4, "percent": 80},
"sensors": ["DHT11", "LDR", "HC-SR04"]
}"""
info = json.loads(robot_json)
print(info["battery"]["percent"]) # do bar keshoo baz kon: 80
print(info["sensors"][0]) # kelid + index-e list: DHT11
چالش: dumps یا loads؟
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
۴. پروژه: ایستگاه هواشناسیِ جهانی#
وقتِ پروژه است. یک سرویسِ هواشناسیِ رایگان و بدونِ ثبتنام هست که آبوهوای هر نقطهٔ زمین را JSON میدهد — اسمش Open-Meteo است و نشانیاش در کدِ پایین آمده است (سرویسها بهروز میشوند، پس اگر روزی جواب نداد، نشانیِ تازه را در سایتِ خودِ Open-Meteo پیدا کن). فقط مختصاتِ شهر را در پارامترهایش میگذاری؛ برای شروع توکیو گذاشتهایم و مختصاتِ هر شهری را از اپِ نقشهٔ گوشی درمیآوری. درخواستِ GET را مثلِ فصل ۲ میفرستیم و با اعتمادبهنفس دما را میخوانیم:
r = urequests.get(URL)
data = r.json()
r.close()
print(data["temperature"])
اجرا و...
Traceback (most recent call last):
File "<stdin>", line 4, in <module>
KeyError: temperature
KeyError یعنی «کشویی با این برچسب پیدا نکردم». ولی مطمئنیم دما آنجاست! قانونِ کارآگاهیِ JSON را یاد بگیر — قدمِ اول همیشه: کلِ نقشه را چاپ کن. یک print(data) بزن:
{'latitude': 35.7, 'longitude': 139.7, 'current_weather': {'temperature': 18.3,
'windspeed': 8.2, 'winddirection': 245, 'is_day': 1}, ...}
آهان! دما در طبقهٔ اول نیست — داخلِ کشوی current_weather است: ساختارِ تودرتو، دقیقاً همان که اولِ فصل تمرین کردیم! پس دو قدم: اول ["current_weather"]، بعد ["temperature"]. و همینجا درسِ اصلی را قاب کن: نقشهای که بالا چاپ شده نقشهٔ همین سرویس در همین لحظه است، نه یک قانونِ ابدی — سرویسها ساختارِ پاسخشان را عوض میکنند. پس هر بار که سراغِ یک سرویسِ تازه میروی، اول print(data)، بعد کلیدزنی. حالا کدِ کامل با OLED، که قالبش را از ایستگاه هواشناسیِ ترم ۲ قرض میگیریم (فایلِ 02_world_weather.py):
# Term 4 - Session 06 - havashenasi-e jahani rooye OLED (noskhe-ye dars)
# URL-e service: gahi avaz mishavad
from machine import Pin, I2C
import network
import urequests
import ssd1306
import time
WIFI_SSID = "esm-e-wifi-khodet"
WIFI_PASS = "password-e-wifi"
# mokhtasat-e Tokyo - mokhtasat-e shahr-e khodet ra az app-e naghshe bardar
URL = "https://api.open-meteo.com/v1/forecast?latitude=35.7&longitude=139.7¤t_weather=true"
i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(WIFI_SSID, WIFI_PASS)
print("dar hal-e ettesal be WiFi...")
tries = 0
while not wlan.isconnected() and tries < 15:
time.sleep(1)
tries = tries + 1
if wlan.isconnected():
print("vasl shod! IP:", wlan.ifconfig()[0])
else:
print("vasl nashod - WiFi ra ba code-haye jalase 1 check kon")
print("gereftan-e ab-o-hava...")
r = urequests.get(URL)
data = r.json() # javab-e JSON -> dictionary (haman json.loads-e makhfi!)
r.close() # azad kardan-e hafeze - hamishe!
weather = data["current_weather"] # ghadam-e 1: keshoo-ye tu-dar-tu
temp = weather["temperature"] # ghadam-e 2: khod-e adad
wind = weather["windspeed"]
print(f"Temp: {temp} C | Wind: {wind} km/h")
oled.fill(0)
oled.text("TOKYO WEATHER", 0, 0)
oled.text(f"TEMP: {temp} C", 0, 20)
oled.text(f"WIND: {wind}", 0, 35)
oled.show()
✅ چک کن: روی OLED باید دمای زندهٔ توکیو را ببینی. دمای توکیو را در مرورگر جستوجو کن: عددش نزدیک است، هرچند سایتهای هواشناسی با هم کمی فرق دارند! این عدد همین لحظه از آنطرفِ کرهٔ زمین آمده و از دلِ JSON، با دو کلیدزنی، بیرون کشیده شده. ایستگاهِ ترم ۲ دماسنجِ اتاقت بود؛ این یکی چشمش به کلِ سیاره است.
🔧 اگر کار نکرد:
KeyErrorگرفتی روی یک کلیدِ دیگر؟ قانونِ کارآگاه: اولprint(data)بزن، نقشه را ببین و لایهبهلایه کلید بزن. اگر موقعِurequests.getخطایOSErrorگرفتی، WiFi وصل نیست یا اینترنت قطع است: اولwlan.isconnected()را چک کن و URL را حرفبهحرف با کدِ همین فصل مقایسه کن. وr.close()را هرگز فراموش نکن، وگرنه حافظهٔ برد پر میشود.
چالش: با KeyError چه میکنی؟
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
۵. کلید API و rate limit#
سرویسِ امروز در نگاهِ اول عجیب بود: نه ثبتنامی، نه رمزی. ولی سرویسهای بزرگتر — مثلِ Gemini که فصلِ بعد سراغش میرویم — درِشان قفل است و برای ورود یک API key میخواهند: یک رشتهٔ طولانی از حرف و عدد که سرویس فقط به تو میدهد. مثلِ چی؟ مثلِ رمزِ عبور. همانقدر شخصی، همانقدر حساس. کلید دو کار میکند: به سرویس میگوید این درخواست از طرفِ کیست، و چقدر از سهمیهاش را مصرف کرده.

و همینجا مفهومِ دوم میآید: rate limit یعنی سقفِ مصرف — مثلِ کارتِ بوفهٔ مدرسه که روزی چند بار بیشتر کار نمیکند. چرا سرویسها سقف میگذارند؟ چون کامپیوترهایشان بینِ میلیونها نفر مشترک است؛ سقف یعنی سهمِ منصفانه برای همه. اگر برنامهات در یک حلقهٔ تند و بیوقفه درخواست بزند، سهمت زود تمام میشود. قانونِ مؤدببودن ساده است: فقط وقتی بپرس که واقعاً لازم داری. برای آبوهوا، هر ده دقیقه یک بار هم زیادی است!

۶. خانهٔ امن: secrets.py#
حالا مهمترین درسِ امنیتیِ دوره. رمز — چه پسوردِ WiFi چه API key — هرگز وسطِ کد نمیماند. چرا؟ چون کد جای نمایش است: به دوستت نشانش میدهی، در گروه میفرستی تا کمکت کنند، در گالریِ عمومیِ آزمایشگاه میگذاری، شاید روزی هم در گیتهاب منتشرش کنی. هر بار، رمزت هم جلوی چشمِ همه است!
راهحلِ حرفهایها ساده و قشنگ است: رمزها به یک فایلِ جدا میروند، و آن یک فایل هرگز جایی نمیرود. از ترم ۳ بلدی ماژولِ خودت را بسازی — robot.py یادت هست؟ حالا یک ماژول میسازیم به اسمِ secrets.py، یعنی «رازها»:
# secrets.py - hame-ye ramz-haye project inja hastand
# IN FILE RA BA HICHKAS SHARE NAKON! na git, na Wokwi-e umumi, na screenshot!
WIFI_SSID = "esm-e-wifi-khodet"
WIFI_PASS = "password-e-wifi"
# jalase 7: kelid-e Gemini API ham inja ezafe mishavad

فایل را با نامِ secrets.py روی برد ذخیره کن — و در کدِ اصلی، بهجای رمزِ لخت، از ماژول بخوان. یادت هست فصل ۱ گفتیم «فعلاً پسورد را همینجا بنویس؛ بعداً جای امنی برایش میسازیم»؟ امروز آن قول ادا میشود:
import secrets
wlan.connect(secrets.WIFI_SSID, secrets.WIFI_PASS)
اجرا... و اگر کار نکرد، احتمالاً این خطا را میبینی:
Traceback (most recent call last):
File "<stdin>", line 5, in <module>
ImportError: no module named 'secrets'
ImportError — همان آشنای فصل قبل: «فایلی به این اسم روی برد نیست». ولی همین الان ذخیرهاش کردی! به لیستِ فایلهای برد در Thonny نگاه کن... آهان: secret.py — بدونِ s آخر! تایپِ اشتباهِ اسمِ فایل، رایجترین دلیلِ این خطاست: import secrets دنبالِ فایلی میگردد که دقیقاً secrets.py باشد. اسمش را درست کن، دوباره اجرا — وصل شد. نسخهٔ نهاییِ ایستگاه که هر ده دقیقه مؤدبانه بهروز میشود، در 03_world_weather_secrets.py است:
# Term 4 - Session 06 - noskhe-ye nahayi: secrets.py + update-e moadab (rate limit!)
# ghabl az ejra: secrets.py bayad ba meghdar-haye vaghei rooye bord bashad
from machine import Pin, I2C
import network
import urequests
import ssd1306
import secrets
import time
# mokhtasat-e Tokyo - mokhtasat-e shahr-e khodet ra az app-e naghshe bardar
URL = "https://api.open-meteo.com/v1/forecast?latitude=35.7&longitude=139.7¤t_weather=true"
UPDATE_SECONDS = 600 # har 10 daghighe yek bar - be rate limit ehteram bogzar!
i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(secrets.WIFI_SSID, secrets.WIFI_PASS) # ramz az khane-ye amn
print("dar hal-e ettesal be WiFi...")
tries = 0
while not wlan.isconnected() and tries < 15:
time.sleep(1)
tries = tries + 1
if wlan.isconnected():
print("vasl shod! IP:", wlan.ifconfig()[0])
else:
print("vasl nashod - WiFi ra ba code-haye jalase 1 check kon")
while True:
try:
r = urequests.get(URL)
data = r.json()
r.close()
weather = data["current_weather"]
temp = weather["temperature"]
wind = weather["windspeed"]
print(f"Temp: {temp} C | Wind: {wind} km/h")
oled.fill(0)
oled.text("WORLD WEATHER", 0, 0)
oled.text(f"TEMP: {temp} C", 0, 20)
oled.text(f"WIND: {wind}", 0, 35)
oled.show()
except OSError:
print("khata dar ettesal! update-e ba'di ra emtehan mikonam")
oled.fill(0)
oled.text("NET ERROR!", 0, 20)
oled.show()
time.sleep(UPDATE_SECONDS)
حالا کدِ اصلیِ تو قابلِ نمایش است: هر که ببیندش، فقط secrets.WIFI_PASS میبیند، نه خودِ رمز را.
⚠️ مواظب باش: اگر روزی رمز یا کلیدت را اشتباهی جایی فرستادی، مثلِ رمزِ عبورِ لورفته رفتار کن: همان لحظه در سایتِ سرویس باطل/عوضش کن، و پسوردِ WiFi را از تنظیماتِ روتر عوض کن. لورفتن مشکلی است که با یک کلیدِ نو حل میشود — بهشرطی که بهموقع بفهمیاش.
چالش: کجا secrets.py «هرگز» نباید دیده شود؟
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
واژههای تازه این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| JSON | جِیسان | زبانِ مشترکِ داده در اینترنت؛ «دیکشنریِ متنشده» |
| Key | کی | کلید؛ برچسبِ کشوی دیکشنری |
| Value | وَلیو | مقدار؛ محتوای کشو |
| Nested | نِستِد | تودرتو؛ قفسهای داخلِ یک کشو |
| Parse | پارس | تجزیهٔ متن به دادهٔ قابلِاستفاده — کاری که loads میکند |
| API key | اِیپیآی کی | رمزِ شخصیِ ورود به یک سرویس — مثلِ رمزِ عبور |
| Rate limit | رِیت لیمیت | سقفِ مصرف؛ سهمِ منصفانهٔ هر کاربر از سرویس |
| Secret | سیکرِت | راز؛ هر چیزی که در secrets.py میماند و جایی نمیرود |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
همهچیز آماده است: زبانِ JSON را بلدی، خانهٔ امنِ کلید را ساختهای، میدانی API key چیست. جلسهٔ بعد روزِ برداشت است: والدینت یک کلیدِ رایگانِ Gemini میسازند و تو برای اولین بار از کدِ خودت به یک هوش مصنوعی پیام میفرستی و جوابش را — بله، به شکلِ JSON! — میگیری. اولین «سلام» بینِ کدِ تو و AI. باور کن، لحظهای است که یادت نمیرود!
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.