شبكة WiFi وخادم HTTP

14.1 العنوان والمنفذ والعميل والخادم – כתובת IP, פורט ומודל לקוח-שרת (IP, Port, Client-Server)

قبل سطر الشيفرة الأول نحتاج إلى أربع كلمات. لكل جهاز في الشبكة عنوان، وفي كل جهاز عدة برامج، ولذلك يحتاج الوصول إلى برنامج معيّن إلى عنوان ورقم معا. وفي كل محادثة طرف يطلب وطرف يجيب.

في هذا الفصل اللوحة هي الخادم. وفي الفصل التالي نعكس الأدوار فتصبح عميلا.

14.2 الانضمام إلى الشبكة – הצטרפות לרשת (Joining a Network)

يعمل الاتصال اللاسلكي في مايكروبايثون عبر الصنف network.WLAN، وله وضعان: في وضع المحطة (תחנה) تنضم اللوحة إلى شبكة قائمة كما يفعل الهاتف، وفي وضع نقطة الوصول (נקודת גישה) تنشئ هي شبكتها الخاصة.

نبدأ بالسؤال: ماذا ترى اللوحة حولها؟ كل نتيجة في المسح (סריקה) تحمل الاسم والقناة وقوة الإشارة. قوة الإشارة rssi عدد سالب، وكلما اقترب من الصفر كانت الإشارة أقوى.

import network

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
for ssid, bssid, channel, rssi, sec, hidden in wlan.scan():
    print(ssid.decode(), channel, rssi)

Home 6 -50
Lab 11 -71
Cafe 1 -85

الأمر connect لا ينتظر: يبدأ الاتصال ويعود فورا. لذلك نسأل isconnected() في حلقة، ونحدّد لها مهلة (פסק זמן) حتى لا يعلق البرنامج إلى الأبد إذا تغيّرت كلمة المرور أو انطفأ الموجّه.

import network
import time
from secrets import WIFI_SSID, WIFI_PASS

WAIT_S = 4

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.disconnect()
wlan.connect(WIFI_SSID, WIFI_PASS)

waited = 0
while not wlan.isconnected() and waited < WAIT_S:
    print("waiting", waited)
    time.sleep(1)
    waited += 1

if wlan.isconnected():
    print("IP:", wlan.ifconfig()[0])
else:
    print("failed, status", wlan.status())
    wlan.active(False)

waiting 0
IP: 192.168.1.50

وقبل connect نستدعي disconnect(): إذا كانت محاولة سابقة ما زالت جارية من تشغيل سابق، يعطي ESP32 الخطأ Wifi Internal Error. ظهر هذا الخطأ فعلا عند تجربة البرنامج على لوحة حقيقية.

والبرنامج نفسه حين تبقى الشبكة بعيدة المنال:

waiting 0
waiting 1
waiting 2
waiting 3
failed, status 201

العدد الذي يعيده status() يفسّره ثابت من الوحدة network، مثل STAT_WRONG_PASSWORD أو STAT_NO_AP_FOUND. والقيم العددية قد تختلف بين اللوحات، فنقارن دائما بالثابت لا بالعدد.

14.3 ملف الأسرار ومكتبة wifi.py – קובץ הסודות וספריית wifi.py

لاحظوا أن كلمة المرور لم تظهر في أي برنامج. فهي في ملف واحد نرفعه إلى اللوحة ولا نرفعه إلى أي مكان آخر:

# secrets.py - your network. Keep it off GitHub and shared folders.
WIFI_SSID = "my-network"
WIFI_PASS = "my-password"
AP_PASS = "pick-a-new-one"

وبما أن كل برنامج في بقية الكتاب يبدأ بالانضمام إلى الشبكة، ننقل الحلقة إلى مكتبة. المكتبة لا تطبع شيئا: إن فشلت أطلقت خطأ، والبرنامج الذي يستدعيها يقرّر ماذا يفعل.

# wifi.py - join the network named in secrets.py, or say why not.
# (c) 2026 Fahed Ghanem - MIT License - fahed-lab.com
import network
import time
from secrets import WIFI_SSID, WIFI_PASS


def connect(timeout_s=15):
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    if wlan.isconnected():
        return wlan
    wlan.disconnect()
    wlan.connect(WIFI_SSID, WIFI_PASS)
    start = time.ticks_ms()
    while not wlan.isconnected():
        if time.ticks_diff(time.ticks_ms(), start) > timeout_s * 1000:
            status = wlan.status()
            wlan.active(False)
            raise OSError("WiFi failed, status %d" % status)
        time.sleep_ms(200)
    return wlan

import wifi

try:
    wlan = wifi.connect(timeout_s=5)
    print("IP:", wlan.ifconfig()[0])
except OSError as e:
    print("no network:", e)

IP: 192.168.1.50

وحين يفشل الاتصال يصل الخطأ إلى except:

no network: WiFi failed, status 201

14.4 اللوحة نقطة وصول – הלוח כנקודת גישה (Access Point Mode)

في الميدان أو في الورشة لا يوجد دائما موجّه. عندها تنشئ اللوحة شبكتها، فنختارها من قائمة الشبكات في الهاتف، ونفتح العنوان الذي تعطيه لنفسها.

import network
from secrets import AP_PASS

ap = network.WLAN(network.AP_IF)
ap.active(True)
ap.config(ssid="lab-board", key=AP_PASS)
ap.active(False)
ap.active(True)
print("network:", ap.config("ssid"))
print("IP:", ap.ifconfig()[0])

network: lab-board
IP: 192.168.4.1

نشغّل الواجهة أولا ثم نضبطها ثم نعيد تشغيلها، لأن هذا الترتيب مقبول في كل الإصدارات: في إصدار قديم من ESP32 يعطي الضبط قبل التشغيل خطأ. ولم نجرّب هذا الترتيب على Pico W حقيقية.

كل ما سيأتي في الفصل من خادم وصفحات يعمل في الوضعين. فالخادم لا يهمّه كيف وصل العميل، بل يهمّه أن يصل.

14.5 خادم HTTP بالمقبس – שרת HTTP ב-socket (An HTTP Server on a Socket)

أول سطر في الطلب يقول كل شيء: الطريقة GET، ثم المسار (נתיב) /on، ثم النسخة. والاستجابة أيضا نص بترتيب ثابت: سطر الحالة، ثم الترويسات (כותרות)، ثم سطر فارغ، ثم الصفحة نفسها.

import socket
import wifi

wlan = wifi.connect()
print("open http://%s/" % wlan.ifconfig()[0])

addr = socket.getaddrinfo("0.0.0.0", 80)[0][-1]
server = socket.socket()
server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
server.bind(addr)
server.listen(2)

while True:
    conn, peer = server.accept()
    request = conn.recv(1024)
    print(peer[0], request.split(b"\r\n")[0].decode())
    conn.sendall(b"HTTP/1.0 200 OK\r\n"
                 b"Content-Type: text/html\r\n\r\n"
                 b"<h1>Hello from the board</h1>")
    conn.close()

open http://192.168.1.50/
192.168.1.20 GET / HTTP/1.1
[http_sent]
HTTP/1.0 200 OK
Content-Type: text/html

<h1>Hello from the board</h1>
...

14.6 صفحة تتحكّم في الثنائي – דף ששולט בנורית (A Page that Drives the LED)

لنبدأ بما سيتكرر: فتح المقبس، وتفكيك السطر الأول، وبناء الاستجابة. نجمع ذلك في مكتبة صغيرة، لتبقى في البرنامج الأسطر التي تقول ماذا يفعل الجهاز.

# miniweb.py - a tiny web server on plain sockets, one client at a time.
# (c) 2026 Fahed Ghanem - MIT License - fahed-lab.com
import socket


def listen(port=80):
    addr = socket.getaddrinfo("0.0.0.0", port)[0][-1]
    server = socket.socket()
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind(addr)
    server.listen(2)
    return server


def parse(raw):
    parts = raw.split(b"\r\n")[0].decode().split(" ")
    if len(parts) < 2:
        return "", {}
    target = parts[1].split("?", 1)
    args = {}
    if len(target) == 2:
        for pair in target[1].split("&"):
            kv = pair.split("=", 1)
            if len(kv) == 2:
                args[kv[0]] = kv[1]
    return target[0], args


def reply(conn, body, status="200 OK", kind="text/html"):
    head = "HTTP/1.0 %s\r\nContent-Type: %s\r\n\r\n" % (status, kind)
    conn.sendall(head.encode() + body.encode())

('/set', {'mode': 'slow', 'level': '60'})

from machine import Pin
import board
import miniweb
import wifi

PAGE = """<h1>LED: %s</h1>
<a href="/on">ON</a> <a href="/off">OFF</a>"""

led = Pin(board.LED, Pin.OUT)
wifi.connect()
server = miniweb.listen()

while True:
    conn, peer = server.accept()
    conn.settimeout(3)
    try:
        path, args = miniweb.parse(conn.recv(1024))
        print(peer[0], path)
        if path == "/on":
            led.value(1)
        elif path == "/off":
            led.value(0)
        if path in ("/", "/on", "/off"):
            state = "ON" if led.value() else "OFF"
            miniweb.reply(conn, PAGE % state)
        else:
            miniweb.reply(conn, "Not found", "404 Not Found")
    except OSError as e:
        print("client error:", e)
    finally:
        conn.close()

192.168.1.20 /
192.168.1.20 /on
192.168.1.20 /favicon.ico
192.168.1.20 /off
[pins]
2 1
2 0
...

192.168.1.20 /
192.168.1.20 /on
192.168.1.20 /favicon.ico
192.168.1.20 /off
[pins]
100 1
100 0
...

انظروا إلى الطلب الثالث: لم نضغط على شيء يقود إلى /favicon.ico. المتصفّحات تطلب هذا الملف من تلقاء نفسها لتعرض أيقونة الموقع، ولذلك يحتاج كل خادم إلى إجابة 404 لما لا يعرفه. والمرور بأي مسار غير معروف لا يغيّر حالة الثنائي.

ولماذا conn.settimeout(3)؟ لأن هذا الخادم يخدم عميلا واحدا في كل مرة. عميل فتح اتصالا ولم يرسل شيئا يوقف الخادم كله عند recv. المهلة تطلق OSError، وfinally يغلق المقبس في كل الأحوال، ويعود الخادم إلى accept.

14.7 عرض قراءة واستقبال قيمة – הצגת קריאה וטופס (Showing a Reading, Receiving a Value)

نخطو خطوة أخيرة: صفحة تعرض جهد مقياس الجهد، وفيها نموذج (טופס) يضبط إضاءة ثنائي خارجي. النموذج في HTML لا يحتاج إلى أي شيفرة خاصة: عند الضغط على الزر يطلب المتصفّح /set?level=60، أي مسار ومعامل، وهذا ما نعرف قراءته.

import board
import miniweb
import wifi
from convert import to_volts

PAGE = """<h1>%.2f V</h1><p>LED: %d%%</p>
<form action="/set">
<input name="level" type="number" min="0" max="100">
<button>Set</button></form>"""

pot = board.analog_in(board.POT)
led = board.pwm(board.LED_EXT, 1000)
led.duty_u16(0)
level = 0
wifi.connect()
server = miniweb.listen()


def handle(path, args):
    global level
    if path == "/set":
        value = int(args["level"])
        if not 0 <= value <= 100:
            raise ValueError("range")
        level = value
        led.duty_u16(level * 65535 // 100)
    elif path != "/":
        return "Not found", "404 Not Found"
    return PAGE % (to_volts(pot.read_u16()), level), "200 OK"


while True:
    conn, peer = server.accept()
    conn.settimeout(3)
    try:
        path, args = miniweb.parse(conn.recv(1024))
        try:
            body, status = handle(path, args)
        except (KeyError, ValueError):
            body, status = "Bad value", "400 Bad Request"
        print(path, args, status, "level", level)
        miniweb.reply(conn, body, status)
    except OSError as e:
        print("client error:", e)
    finally:
        conn.close()

/ {} 200 OK level 0
/set {'level': '60'} 200 OK level 60
/set {'level': 'abc'} 400 Bad Request level 60
/set {'level': '150'} 400 Bad Request level 60
/set {} 400 Bad Request level 60
[pwm]
13 0
13 39321
...

/ {} 200 OK level 0
/set {'level': '60'} 200 OK level 60
/set {'level': 'abc'} 400 Bad Request level 60
/set {'level': '150'} 400 Bad Request level 60
/set {} 400 Bad Request level 60
[pwm]
15 0
15 39321
...

14.8 حدود الأمان – אבטחה: מה מותר לחבר (Security Limits)

الخادم الذي كتبناه يعمل، لكن علينا أن نقول بوضوح ما الذي ينقصه:

• لا تشفير (הצפנה): كل طلب واستجابة نص مكشوف. كلمة مرور الشبكة تمنع الغرباء من دخول الشبكة، لكنها لا تخفي الحركة عن كل من دخلها.
• لا مصادقة (אימות): الخادم لا يسأل من الطالب. كل جهاز في الشبكة، بما فيه هاتف الضيف، يستطيع طلب /on.
• لا إضافة بسيطة تحل ذلك: كلمة مرور ترسلها الصفحة في طلب HTTP تمر هي أيضا نصا مكشوفا.

القاعدة التي نعمل بها: هذا الخادم لشبكة مختبر نعرف كل من فيها. وكل مشغّل نصله به نختار له حالة لا تضر عند انقطاع الشبكة، وهذا يقرّره البرنامج وليس الشبكة.

14.9 فروق اللوحات والنشر – הבדלים בין הלוחות ופריסה (Board Differences, Deployment)

نعود إلى ما وعدنا به في فصل القراءة التماثلية. على ESP32 كتلة المحوّلات الثانية يستعملها WiFi، فالقراءة من طرف فيها تفشل ما دامت البطاقة مفعّلة:

from machine import ADC, Pin
import network

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
pot = ADC(Pin(25), atten=ADC.ATTN_11DB)
print(pot.read_u16())

OSError: ADC2 is in use by WiFi

لهذا كان board.POT على ESP32 الطرف 34، وهو من المجال 32–39. أما على Pico W فلا يوجد هذا القيد، والأطراف GP26–GP28 تعمل مع الشبكة.

كل برامج الفصل عملت على اللوحتين دون تعديل سطر، وهذا ما عرضته الشاشات أعلاه. والعمل الوحيد هو رفع الملفات التي تستوردها إلى اللوحة، ثم تسمية البرنامج main.py ليعمل عند التشغيل:

mpremote cp secrets.py wifi.py miniweb.py board.py convert.py :
mpremote cp http_panel.py :main.py
mpremote reset

أهمّ أفكار الفصل:

• الوصول إلى برنامج في الشبكة يحتاج إلى عنوان IP ومنفذ.
• الانتظار دائما بمهلة، والفشل حالة عادية يعالجها البرنامج.
• كلمات المرور والمفاتيح في secrets.py، ولا تدخل أبدا في شيفرة مشتركة.
• بروتوكول HTTP نص: طلب، فسطر حالة وترويسات، فسطر فارغ، فصفحة.
• كل قيمة من الشبكة نتحقق منها في اللوحة، وكل مقبس نغلقه في finally.
• لا تشفير ولا مصادقة هنا: الخادم لشبكة مختبر ولأحمال لا تضر.
• على ESP32 مع WiFi نقرأ من الأطراف 32–39 فقط.

أوامر الفصل:

قاموس المصطلحات – מילון מונחים:

أسئلة للتمرين:

if path == "/toggle":
    led.value(1 - led.value())

import json

if path == "/api":
    volts = to_volts(pot.read_u16())
    text = json.dumps({"volts": volts, "level": level})
    miniweb.reply(conn, text, "200 OK", "application/json")