ESP32 : Migration de la version 2.x vers la version 3.0 (IDE Arduino)

Récemment, l’ESP-IDF a été mis à jour et avec cette nouvelle version majeure, des modifications majeures ont été apportées à l’API. Dans ce guide, vous découvrirez toutes les modifications apportées à l’API et comment migrer vers la dernière version.

Ce guide couvre les modifications depuis les versions 2.X du module complémentaire de la carte ESP32 (basées sur ESP-IDF 4.4) vers la version 3.0 (basée sur ESP-IDF 5.1) du noyau Arduino ESP32 – vous pouvez trouver plus d’informations dans le guide de migration officiel .

Si vous avez récemment mis à jour le module complémentaire de vos cartes ESP32 vers la version 3.0 et que vous obtenez maintenant des erreurs de compilation dans votre code, vous devez consulter ce guide.

Vérification de la version de votre carte ESP32 installée

Tout d’abord, vous devez vérifier quelle version des cartes ESP32 vous avez installée dans votre IDE Arduino. Accédez à Outils > Tableau et sélectionnez l’option Gestionnaire de tableaux….

Ensuite, recherchez « ESP32 » par Espressif Systems et vérifiez quelle version vous avez installée dans votre IDE Arduino – si votre installation est à jour, vous devriez avoir la version 3.0.X.

Important : dans les semaines à venir, tout le code disponible dans nos projets ESP32 sur les didacticiels Random Nerd sera mis à jour pour être compatible avec la version 3.0. En attendant, si votre code ne se compile pas en raison de ce changement récent, vous pouvez rétrograder le module complémentaire de vos cartes ESP32 vers la version 2.0.17 pour garantir que votre code se compile et s’exécute correctement.

Table des matières

Voici un résumé des changements. Pour la liste complète des modifications, consultez le guide de migration officiel.

ADC – API supprimées

• analogSetClockDiv
• adcAttachPin
• analogSetVRefPin

BLE – Modifications des API

• Modification du retour des API et du type de paramètre de std::string à String de style Arduino.
• Modification du type de données UUID de uint16_t à la classe BLEUUID.
• Les méthodes BLEScan::start et BLEScan::getResults renvoient le type modifié de BLEScanResults à BLEScanResults*.

LEDC – API supprimée

LEDC – Nouvelles API

L’API LEDC a été modifiée pour prendre en charge le gestionnaire de périphériques et la rendre plus facile à utiliser, car les canaux LEDC sont désormais automatiquement attribués aux broches (en savoir plus sur la nouvelle API LEDC).

• ledcAttach utilisé pour configurer la broche LEDC (fonctions ledcSetup et ledcAttachPin fusionnées).
• ledcOutputInvert utilisé pour attacher l’interruption à une minuterie à l’aide d’arguments.
• ledcFade utilisé pour configurer et démarrer un fondu sur une broche LEDC donnée.
• ledcFadeWithInterrupt utilisé pour configurer et démarrer un fondu sur une broche LEDC donnée avec une interruption.
• ledcFadeWithInterruptArg utilisé pour configurer et démarrer un fondu sur une broche LEDC donnée avec une interruption à l’aide d’arguments.

Vous pouvez maintenant utiliser analogWrite() pour générer un signal PWM. Passez en argument le GPIO, et le duty cycle.

void analogWrite(uint8_t pin, int value);

Si vous utilisez la fonction ledcWrite(), elle n’accepte désormais que deux arguments (le GPIO et le rapport cyclique).

bool ledcWrite(uint8_t pin, uint32_t duty);

Vous n’avez plus besoin d’attribuer un canal PWM. Il sera automatiquement attribué. Si vous souhaitez attribuer un canal PWM spécifique, utilisez ledcAttachChannel().

bool ledcAttachChannel(uint8_t pin, uint32_t freq, uint8_t resolution, int8_t channel);

LEDC – Modifications des API

• ledcDetachPin renommé ledcDetach.
• Dans toutes les fonctions, le canal de paramètres d’entrée a été remplacé par pin.

Capteur à effet Hall – API supprimée

• hallRead : le capteur Hall n’est plus pris en charge.

WiFi – Modifications fonctionnelles

• Dans Arduino (et d’autres frameworks), la méthode nommée flush() est destinée à envoyer le contenu du tampon de transmission. La méthode WiFiClient et WiFiUDP flush() n’effacera plus le tampon de réception. Une nouvelle méthode appelée clear() est désormais utilisée à cet effet. Actuellement, flush() ne fait rien dans WiFiClient, WiFiClientSecure et WiFiUDP.
• WiFiServer a les fonctions accept() et available() avec les mêmes fonctionnalités. Dans Arduino, available() devrait fonctionner différemment, il est donc désormais obsolète.
• WiFiServer avait des fonctions d’écriture non implémentées héritées de la classe Print. Ceux-ci sont désormais supprimés. La méthode stopAll() non implémentée est également supprimée. Les méthodes n’ont pas été implémentées car WiFiServer ne gère pas les objets WiFiClient connectés pour la fonctionnalité d’impression sur tous les clients.

Nom de l’événement WiFi – Modifications

Les noms des événements Wi-Fi ont changé. Ce sont les nouveaux événements.

I2S – Nouvelle API

Le pilote I2S a été entièrement repensé et refactorisé pour utiliser le nouveau pilote ESP-IDF – API I2S.

RMT – API supprimées

• _rmtDumpStatus
• rmtSetTick
• rmtWriteBlocking
• rmtFin
• rmtBeginReceive
• rmtReadData

RMT – Nouvelles API

Pour plus d’informations sur la nouvelle API RMT.

• rmtSetEOT
• rmtWriteAsync
• rmtTransmitCompleted
• rmtSetRxMinThreshold

RMT – Modifications des API

Dans toutes les fonctions, le paramètre d’entrée rmt_obj_t* rmt a été remplacé par int pin.

• Le paramètre de retour rmtInit a été modifié en bool.
• Le paramètre d’entrée rmtInit bool tx_not_rx a été remplacé par rmt_ch_dir_t channel_direction.
• rmtInit nouveau paramètre d’entrée uint32_t Frequency_Hz pour définir la fréquence du canal RMT (car la fonction rmtSetTick a été supprimée).
• rmtWrite envoie désormais des données en mode blocage. Il ne revient qu’après l’envoi de toutes les données ou après un délai d’attente. Pour le mode Async, utilisez la nouvelle fonction rmtWriteAsync.
• rmtWrite nouveau paramètre d’entrée uint32_t timeout_ms.
• rmtLoop renommé rmtWriteLooping.
• Les paramètres d’entrée rmtRead ont été modifiés en int pin, rmt_data_t* data, size_t *num_rmt_symbols, uint32_t timeout_ms.
• Les paramètres d’entrée rmtReadAsync ont été modifiés en int pin, rmt_data_t* data, size_t *num_rmt_symbols.
• rmtSetRxThreshold a été renommé rmtSetRxMaxThreshold et la valeur du paramètre d’entrée uint32_t a été modifiée en uint16_t ralenti_thres_ticks.
• Les paramètres d’entrée rmtSetCarrier uint32_t low, uint32_t high ont été modifiés en uint32_t Frequency_Hz, float duty_percent.

SigmaDelta – API supprimées

• sigmaDeltaConfiguration
• sigmaDeltaLecture

SigmaDelta – Nouvelles API

SigmaDelta a été refactorisé pour utiliser le nouveau pilote ESP-IDF – API SigmaDelta.

• sigmaDeltaAttach utilisé pour configurer la broche SigmaDelta (le canal est acquis automatiquement).
• timerGetFrequency utilisé pour obtenir la fréquence réelle de la minuterie.
• timerAttachInterruptArg utilisé pour attacher l’interruption à un minuteur à l’aide d’arguments.

SigmaDelta – Modifications des API

• sigmaDeltaDetachPin renommé sigmaDeltaDetach.
• Le canal de paramètres d’entrée sigmaDeltaWrite a été remplacé par pin.

Minuterie – API supprimées

• timerGetConfig
• timerSetConfig
• timerSetDivider
• timerSetCountUp
• timerSetAutoReload
• minuterieGetDivider
• minuterieGetCountUp
• timerGetAutoReload
• timerAlarmEnable
• minuterieAlarmeDésactiver
• timerAlarmWrite
• timerAlarmEnabled
• minuterieAlarmeLecture
• timerAlarmReadMicros
• timerAlarmReadSeconds
• timerAttachInterruptFlag

Minuterie – Nouvelles API

Timer a été remanié pour utiliser le nouveau pilote ESP-IDF et son API a été simplifiée – nouvelle API Timer.

• timerAlarm utilisé pour configurer l’alarme pour la minuterie et l’activer automatiquement (fonctions timerAlarmWrite et timerAlarmEnable fusionnées).
• timerGetFrequency utilisé pour obtenir la fréquence réelle de la minuterie.
• timerAttachInterruptArg utilisé pour attacher l’interruption à un minuteur à l’aide d’arguments.

Minuterie – Modifications des API

• timerBegin n’a désormais qu’un seul paramètre (fréquence). Il existe un calcul automatique du diviseur utilisant différentes sources d’horloge pour atteindre la fréquence sélectionnée.
• timerAttachInterrupt n’a désormais que 2 paramètres. Le paramètre edge a été supprimé.

UART (HardwareSerial) – Modifications des API

• Le mode uint8_t du paramètre d’entrée setHwFlowCtrlMode a été modifié en mode SerialHwFlowCtrl.
• Le mode uint8_t du paramètre d’entrée setMode a été modifié en mode SerialMode.

UART (HardwareSerial) – Modifications fonctionnelles

• Les broches par défaut de certains SoC ont été modifiées pour éviter les conflits avec d’autres périphériques : * Les broches UART1 RX et TX de l’ESP32 sont désormais respectivement GPIO26 et GPIO27 ; * Les broches UART2 RX et TX de l’ESP32 sont désormais respectivement GPIO4 et GPIO25 ; * Les broches UART1 RX et TX de l’ESP32-S2 sont désormais respectivement GPIO4 et GPIO5.
• Il est désormais possible de détacher les broches UART0 en appelant end() sans appel préalable de start().
• Il est désormais possible d’appeler setPins() avant start() ou dans n’importe quel ordre.
• setPins() détachera toutes les broches précédentes qui ont été modifiées.
• start(baud, rx, tx) détachera toutes les broches précédemment attachées.
• setPins() ou begin(baud, rx, tx) lorsqu’ils sont appelés pour la première fois, détacheront la console RX0/TX0, connectée au démarrage.
• Toute broche définie sur -1 dans begin() ou setPins() ne sera ni modifiée ni détachée.
• Begin(baud) ne modifiera aucune des broches définies avant cet appel, via un début(baud, rx, tx) ou setPin() précédent.
• Si l’application utilise uniquement RX ou TX, start(baud, -1, tx) ou start(baud, rx) modifiera uniquement la broche attribuée et conservera l’autre inchangée.

Conclusion

Si vous utilisez Arduino IDE 2, vous avez probablement déjà mis à jour l’installation de vos cartes ESP32 vers la version 3.0. Des modifications importantes ont été apportées entre la version 2 et la version 3. Ainsi, vos anciens codes risquent de ne plus être compilés avec cette nouvelle version.

Si tel est le cas, vous pouvez essayer d’utiliser ce guide pour mettre à jour votre code afin qu’il soit compatible avec la version la plus récente, ou rétrograder votre installation vers la version 2.

Nous mettrons à jour tous nos exemples pour être compatibles avec la version 3 dans les semaines à venir.

Cette vidéo vous emmène dans l’histoire de Raspberry Pi :