-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathesptool.py
5387 lines (4459 loc) · 262 KB
/
esptool.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/python
#
# SPDX-FileCopyrightText: 2014-2022 Fredrik Ahlberg, Angus Gratton, Espressif Systems (Shanghai) CO LTD, other contributors as noted.
#
# SPDX-License-Identifier: GPL-2.0-or-later
from __future__ import division, print_function
import argparse
import base64
import binascii
import copy
import hashlib
import inspect
import io
import itertools
import os
import re
import shlex
import string
import struct
import sys
import time
import zlib
try:
import serial
except ImportError:
print("Pyserial is not installed for %s. Check the README for installation instructions." % (sys.executable))
raise
# check 'serial' is 'pyserial' and not 'serial' https://github.com/espressif/esptool/issues/269
try:
if "serialization" in serial.__doc__ and "deserialization" in serial.__doc__:
raise ImportError("""
esptool.py depends on pyserial, but there is a conflict with a currently installed package named 'serial'.
You may be able to work around this by 'pip uninstall serial; pip install pyserial' \
but this may break other installed Python software that depends on 'serial'.
There is no good fix for this right now, apart from configuring virtualenvs. \
See https://github.com/espressif/esptool/issues/269#issuecomment-385298196 for discussion of the underlying issue(s).""")
except TypeError:
pass # __doc__ returns None for pyserial
try:
import serial.tools.list_ports as list_ports
except ImportError:
print("The installed version (%s) of pyserial appears to be too old for esptool.py (Python interpreter %s). "
"Check the README for installation instructions." % (sys.VERSION, sys.executable))
raise
except Exception:
if sys.platform == "darwin":
# swallow the exception, this is a known issue in pyserial+macOS Big Sur preview ref https://github.com/espressif/esptool/issues/540
list_ports = None
else:
raise
__version__ = "3.3"
MAX_UINT32 = 0xffffffff
MAX_UINT24 = 0xffffff
DEFAULT_TIMEOUT = 3 # timeout for most flash operations
START_FLASH_TIMEOUT = 20 # timeout for starting flash (may perform erase)
CHIP_ERASE_TIMEOUT = 120 # timeout for full chip erase
MAX_TIMEOUT = CHIP_ERASE_TIMEOUT * 2 # longest any command can run
SYNC_TIMEOUT = 0.1 # timeout for syncing with bootloader
MD5_TIMEOUT_PER_MB = 8 # timeout (per megabyte) for calculating md5sum
ERASE_REGION_TIMEOUT_PER_MB = 30 # timeout (per megabyte) for erasing a region
ERASE_WRITE_TIMEOUT_PER_MB = 40 # timeout (per megabyte) for erasing and writing data
MEM_END_ROM_TIMEOUT = 0.05 # special short timeout for ESP_MEM_END, as it may never respond
DEFAULT_SERIAL_WRITE_TIMEOUT = 10 # timeout for serial port write
DEFAULT_CONNECT_ATTEMPTS = 7 # default number of times to try connection
SUPPORTED_CHIPS = ['esp8266', 'esp32', 'esp32s2', 'esp32s3beta2', 'esp32s3', 'esp32c3', 'esp32c6beta', 'esp32h2beta1', 'esp32h2beta2', 'esp32c2']
def timeout_per_mb(seconds_per_mb, size_bytes):
""" Scales timeouts which are size-specific """
result = seconds_per_mb * (size_bytes / 1e6)
if result < DEFAULT_TIMEOUT:
return DEFAULT_TIMEOUT
return result
def _chip_to_rom_loader(chip):
return {
'esp8266': ESP8266ROM,
'esp32': ESP32ROM,
'esp32s2': ESP32S2ROM,
'esp32s3beta2': ESP32S3BETA2ROM,
'esp32s3': ESP32S3ROM,
'esp32c3': ESP32C3ROM,
'esp32c6beta': ESP32C6BETAROM,
'esp32h2beta1': ESP32H2BETA1ROM,
'esp32h2beta2': ESP32H2BETA2ROM,
'esp32c2': ESP32C2ROM,
}[chip]
def get_default_connected_device(serial_list, port, connect_attempts, initial_baud, chip='auto', trace=False,
before='default_reset'):
_esp = None
for each_port in reversed(serial_list):
print("Serial port %s" % each_port)
try:
if chip == 'auto':
_esp = ESPLoader.detect_chip(each_port, initial_baud, before, trace,
connect_attempts)
else:
chip_class = _chip_to_rom_loader(chip)
_esp = chip_class(each_port, initial_baud, trace)
_esp.connect(before, connect_attempts)
break
except (FatalError, OSError) as err:
if port is not None:
raise
print("%s failed to connect: %s" % (each_port, err))
_esp = None
return _esp
DETECTED_FLASH_SIZES = {0x12: '256KB', 0x13: '512KB', 0x14: '1MB',
0x15: '2MB', 0x16: '4MB', 0x17: '8MB',
0x18: '16MB', 0x19: '32MB', 0x1a: '64MB', 0x21: '128MB'}
def check_supported_function(func, check_func):
"""
Decorator implementation that wraps a check around an ESPLoader
bootloader function to check if it's supported.
This is used to capture the multidimensional differences in
functionality between the ESP8266 & ESP32 (and later chips) ROM loaders, and the
software stub that runs on these. Not possible to do this cleanly
via inheritance alone.
"""
def inner(*args, **kwargs):
obj = args[0]
if check_func(obj):
return func(*args, **kwargs)
else:
raise NotImplementedInROMError(obj, func)
return inner
def esp8266_function_only(func):
""" Attribute for a function only supported on ESP8266 """
return check_supported_function(func, lambda o: o.CHIP_NAME == "ESP8266")
def stub_function_only(func):
""" Attribute for a function only supported in the software stub loader """
return check_supported_function(func, lambda o: o.IS_STUB)
def stub_and_esp32_function_only(func):
""" Attribute for a function only supported by software stubs or ESP32 and later chips ROM """
return check_supported_function(func, lambda o: o.IS_STUB or isinstance(o, ESP32ROM))
def esp32s3_or_newer_function_only(func):
""" Attribute for a function only supported by ESP32S3 and later chips ROM """
return check_supported_function(func, lambda o: isinstance(o, ESP32S3ROM) or isinstance(o, ESP32C3ROM))
PYTHON2 = sys.version_info[0] < 3 # True if on pre-Python 3
# Function to return nth byte of a bitstring
# Different behaviour on Python 2 vs 3
if PYTHON2:
def byte(bitstr, index):
return ord(bitstr[index])
else:
def byte(bitstr, index):
return bitstr[index]
# Provide a 'basestring' class on Python 3
try:
basestring
except NameError:
basestring = str
def print_overwrite(message, last_line=False):
""" Print a message, overwriting the currently printed line.
If last_line is False, don't append a newline at the end (expecting another subsequent call will overwrite this one.)
After a sequence of calls with last_line=False, call once with last_line=True.
If output is not a TTY (for example redirected a pipe), no overwriting happens and this function is the same as print().
"""
if sys.stdout.isatty():
print("\r%s" % message, end='\n' if last_line else '')
else:
print(message)
def _mask_to_shift(mask):
""" Return the index of the least significant bit in the mask """
shift = 0
while mask & 0x1 == 0:
shift += 1
mask >>= 1
return shift
class ESPLoader(object):
""" Base class providing access to ESP ROM & software stub bootloaders.
Subclasses provide ESP8266 & ESP32 Family specific functionality.
Don't instantiate this base class directly, either instantiate a subclass or
call ESPLoader.detect_chip() which will interrogate the chip and return the
appropriate subclass instance.
"""
CHIP_NAME = "Espressif device"
IS_STUB = False
FPGA_SLOW_BOOT = False
DEFAULT_PORT = "/dev/ttyUSB0"
USES_RFC2217 = False
# Commands supported by ESP8266 ROM bootloader
ESP_FLASH_BEGIN = 0x02
ESP_FLASH_DATA = 0x03
ESP_FLASH_END = 0x04
ESP_MEM_BEGIN = 0x05
ESP_MEM_END = 0x06
ESP_MEM_DATA = 0x07
ESP_SYNC = 0x08
ESP_WRITE_REG = 0x09
ESP_READ_REG = 0x0a
# Some comands supported by ESP32 and later chips ROM bootloader (or -8266 w/ stub)
ESP_SPI_SET_PARAMS = 0x0B
ESP_SPI_ATTACH = 0x0D
ESP_READ_FLASH_SLOW = 0x0e # ROM only, much slower than the stub flash read
ESP_CHANGE_BAUDRATE = 0x0F
ESP_FLASH_DEFL_BEGIN = 0x10
ESP_FLASH_DEFL_DATA = 0x11
ESP_FLASH_DEFL_END = 0x12
ESP_SPI_FLASH_MD5 = 0x13
# Commands supported by ESP32-S2 and later chips ROM bootloader only
ESP_GET_SECURITY_INFO = 0x14
# Some commands supported by stub only
ESP_ERASE_FLASH = 0xD0
ESP_ERASE_REGION = 0xD1
ESP_READ_FLASH = 0xD2
ESP_RUN_USER_CODE = 0xD3
# Flash encryption encrypted data command
ESP_FLASH_ENCRYPT_DATA = 0xD4
# Response code(s) sent by ROM
ROM_INVALID_RECV_MSG = 0x05 # response if an invalid message is received
# Maximum block sized for RAM and Flash writes, respectively.
ESP_RAM_BLOCK = 0x1800
FLASH_WRITE_SIZE = 0x400
# Default baudrate. The ROM auto-bauds, so we can use more or less whatever we want.
ESP_ROM_BAUD = 115200
# First byte of the application image
ESP_IMAGE_MAGIC = 0xe9
# Initial state for the checksum routine
ESP_CHECKSUM_MAGIC = 0xef
# Flash sector size, minimum unit of erase.
FLASH_SECTOR_SIZE = 0x1000
UART_DATE_REG_ADDR = 0x60000078
CHIP_DETECT_MAGIC_REG_ADDR = 0x40001000 # This ROM address has a different value on each chip model
UART_CLKDIV_MASK = 0xFFFFF
# Memory addresses
IROM_MAP_START = 0x40200000
IROM_MAP_END = 0x40300000
# The number of bytes in the UART response that signify command status
STATUS_BYTES_LENGTH = 2
# Response to ESP_SYNC might indicate that flasher stub is running instead of the ROM bootloader
sync_stub_detected = False
# Device PIDs
USB_JTAG_SERIAL_PID = 0x1001
# Chip IDs that are no longer supported by esptool
UNSUPPORTED_CHIPS = {6: "ESP32-S3(beta 3)"}
def __init__(self, port=DEFAULT_PORT, baud=ESP_ROM_BAUD, trace_enabled=False):
"""Base constructor for ESPLoader bootloader interaction
Don't call this constructor, either instantiate ESP8266ROM
or ESP32ROM, or use ESPLoader.detect_chip().
This base class has all of the instance methods for bootloader
functionality supported across various chips & stub
loaders. Subclasses replace the functions they don't support
with ones which throw NotImplementedInROMError().
"""
self.secure_download_mode = False # flag is set to True if esptool detects the ROM is in Secure Download Mode
self.stub_is_disabled = False # flag is set to True if esptool detects conditions which require the stub to be disabled
if isinstance(port, basestring):
self._port = serial.serial_for_url(port)
else:
self._port = port
self._slip_reader = slip_reader(self._port, self.trace)
# setting baud rate in a separate step is a workaround for
# CH341 driver on some Linux versions (this opens at 9600 then
# sets), shouldn't matter for other platforms/drivers. See
# https://github.com/espressif/esptool/issues/44#issuecomment-107094446
self._set_port_baudrate(baud)
self._trace_enabled = trace_enabled
# set write timeout, to prevent esptool blocked at write forever.
try:
self._port.write_timeout = DEFAULT_SERIAL_WRITE_TIMEOUT
except NotImplementedError:
# no write timeout for RFC2217 ports
# need to set the property back to None or it will continue to fail
self._port.write_timeout = None
@property
def serial_port(self):
return self._port.port
def _set_port_baudrate(self, baud):
try:
self._port.baudrate = baud
except IOError:
raise FatalError("Failed to set baud rate %d. The driver may not support this rate." % baud)
@staticmethod
def detect_chip(port=DEFAULT_PORT, baud=ESP_ROM_BAUD, connect_mode='default_reset', trace_enabled=False,
connect_attempts=DEFAULT_CONNECT_ATTEMPTS):
""" Use serial access to detect the chip type.
First, get_security_info command is sent to detect the ID of the chip
(supported only by ESP32-C3 and later, works even in the Secure Download Mode).
If this fails, we reconnect and fall-back to reading the magic number.
It's mapped at a specific ROM address and has a different value on each chip model.
This way we can use one memory read and compare it to the magic number for each chip type.
This routine automatically performs ESPLoader.connect() (passing
connect_mode parameter) as part of querying the chip.
"""
inst = None
detect_port = ESPLoader(port, baud, trace_enabled=trace_enabled)
if detect_port.serial_port.startswith("rfc2217:"):
detect_port.USES_RFC2217 = True
detect_port.connect(connect_mode, connect_attempts, detecting=True)
try:
print('Detecting chip type...', end='')
res = detect_port.check_command('get security info', ESPLoader.ESP_GET_SECURITY_INFO, b'')
res = struct.unpack("<IBBBBBBBBI", res[:16]) # 4b flags, 1b flash_crypt_cnt, 7*1b key_purposes, 4b chip_id
chip_id = res[9] # 2/4 status bytes invariant
for cls in [ESP32S3BETA2ROM, ESP32S3ROM, ESP32C3ROM, ESP32C6BETAROM, ESP32H2BETA1ROM, ESP32C2ROM, ESP32H2BETA2ROM]:
if chip_id == cls.IMAGE_CHIP_ID:
inst = cls(detect_port._port, baud, trace_enabled=trace_enabled)
inst._post_connect()
try:
inst.read_reg(ESPLoader.CHIP_DETECT_MAGIC_REG_ADDR) # Dummy read to check Secure Download mode
except UnsupportedCommandError:
inst.secure_download_mode = True
except (UnsupportedCommandError, struct.error, FatalError) as e:
# UnsupportedCmdErr: ESP8266/ESP32 ROM | struct.err: ESP32-S2 | FatalErr: ESP8266/ESP32 STUB
print(" Unsupported detection protocol, switching and trying again...")
try:
# ESP32/ESP8266 are reset after an unsupported command, need to connect again (not needed on ESP32-S2)
if not isinstance(e, struct.error):
detect_port.connect(connect_mode, connect_attempts, detecting=True, warnings=False)
print('Detecting chip type...', end='')
sys.stdout.flush()
chip_magic_value = detect_port.read_reg(ESPLoader.CHIP_DETECT_MAGIC_REG_ADDR)
for cls in [ESP8266ROM, ESP32ROM, ESP32S2ROM, ESP32S3BETA2ROM, ESP32S3ROM,
ESP32C3ROM, ESP32C6BETAROM, ESP32H2BETA1ROM, ESP32C2ROM, ESP32H2BETA2ROM]:
if chip_magic_value in cls.CHIP_DETECT_MAGIC_VALUE:
inst = cls(detect_port._port, baud, trace_enabled=trace_enabled)
inst._post_connect()
inst.check_chip_id()
except UnsupportedCommandError:
raise FatalError("Unsupported Command Error received. Probably this means Secure Download Mode is enabled, "
"autodetection will not work. Need to manually specify the chip.")
finally:
if inst is not None:
print(' %s' % inst.CHIP_NAME, end='')
if detect_port.sync_stub_detected:
inst = inst.STUB_CLASS(inst)
inst.sync_stub_detected = True
print('') # end line
return inst
raise FatalError("Unexpected CHIP magic value 0x%08x. Failed to autodetect chip type." % (chip_magic_value))
""" Read a SLIP packet from the serial port """
def read(self):
return next(self._slip_reader)
""" Write bytes to the serial port while performing SLIP escaping """
def write(self, packet):
buf = b'\xc0' \
+ (packet.replace(b'\xdb', b'\xdb\xdd').replace(b'\xc0', b'\xdb\xdc')) \
+ b'\xc0'
self.trace("Write %d bytes: %s", len(buf), HexFormatter(buf))
self._port.write(buf)
def trace(self, message, *format_args):
if self._trace_enabled:
now = time.time()
try:
delta = now - self._last_trace
except AttributeError:
delta = 0.0
self._last_trace = now
prefix = "TRACE +%.3f " % delta
print(prefix + (message % format_args))
""" Calculate checksum of a blob, as it is defined by the ROM """
@staticmethod
def checksum(data, state=ESP_CHECKSUM_MAGIC):
for b in data:
if type(b) is int: # python 2/3 compat
state ^= b
else:
state ^= ord(b)
return state
""" Send a request and read the response """
def command(self, op=None, data=b"", chk=0, wait_response=True, timeout=DEFAULT_TIMEOUT):
saved_timeout = self._port.timeout
new_timeout = min(timeout, MAX_TIMEOUT)
if new_timeout != saved_timeout:
self._port.timeout = new_timeout
try:
if op is not None:
self.trace("command op=0x%02x data len=%s wait_response=%d timeout=%.3f data=%s",
op, len(data), 1 if wait_response else 0, timeout, HexFormatter(data))
pkt = struct.pack(b'<BBHI', 0x00, op, len(data), chk) + data
self.write(pkt)
if not wait_response:
return
# tries to get a response until that response has the
# same operation as the request or a retries limit has
# exceeded. This is needed for some esp8266s that
# reply with more sync responses than expected.
for retry in range(100):
p = self.read()
if len(p) < 8:
continue
(resp, op_ret, len_ret, val) = struct.unpack('<BBHI', p[:8])
if resp != 1:
continue
data = p[8:]
if op is None or op_ret == op:
return val, data
if byte(data, 0) != 0 and byte(data, 1) == self.ROM_INVALID_RECV_MSG:
self.flush_input() # Unsupported read_reg can result in more than one error response for some reason
raise UnsupportedCommandError(self, op)
finally:
if new_timeout != saved_timeout:
self._port.timeout = saved_timeout
raise FatalError("Response doesn't match request")
def check_command(self, op_description, op=None, data=b'', chk=0, timeout=DEFAULT_TIMEOUT):
"""
Execute a command with 'command', check the result code and throw an appropriate
FatalError if it fails.
Returns the "result" of a successful command.
"""
val, data = self.command(op, data, chk, timeout=timeout)
# things are a bit weird here, bear with us
# the status bytes are the last 2/4 bytes in the data (depending on chip)
if len(data) < self.STATUS_BYTES_LENGTH:
raise FatalError("Failed to %s. Only got %d byte status response." % (op_description, len(data)))
status_bytes = data[-self.STATUS_BYTES_LENGTH:]
# we only care if the first one is non-zero. If it is, the second byte is a reason.
if byte(status_bytes, 0) != 0:
raise FatalError.WithResult('Failed to %s' % op_description, status_bytes)
# if we had more data than just the status bytes, return it as the result
# (this is used by the md5sum command, maybe other commands?)
if len(data) > self.STATUS_BYTES_LENGTH:
return data[:-self.STATUS_BYTES_LENGTH]
else: # otherwise, just return the 'val' field which comes from the reply header (this is used by read_reg)
return val
def flush_input(self):
self._port.flushInput()
self._slip_reader = slip_reader(self._port, self.trace)
def sync(self):
val, _ = self.command(self.ESP_SYNC, b'\x07\x07\x12\x20' + 32 * b'\x55',
timeout=SYNC_TIMEOUT)
# ROM bootloaders send some non-zero "val" response. The flasher stub sends 0. If we receive 0 then it
# probably indicates that the chip wasn't or couldn't be reseted properly and esptool is talking to the
# flasher stub.
self.sync_stub_detected = val == 0
for _ in range(7):
val, _ = self.command()
self.sync_stub_detected &= val == 0
def _setDTR(self, state):
self._port.setDTR(state)
def _setRTS(self, state):
self._port.setRTS(state)
# Work-around for adapters on Windows using the usbser.sys driver:
# generate a dummy change to DTR so that the set-control-line-state
# request is sent with the updated RTS state and the same DTR state
self._port.setDTR(self._port.dtr)
def _get_pid(self):
if list_ports is None:
print("\nListing all serial ports is currently not available. Can't get device PID.")
return
active_port = self._port.port
# Pyserial only identifies regular ports, URL handlers are not supported
if not active_port.lower().startswith(("com", "/dev/")):
print("\nDevice PID identification is only supported on COM and /dev/ serial ports.")
return
# Return the real path if the active port is a symlink
if active_port.startswith("/dev/") and os.path.islink(active_port):
active_port = os.path.realpath(active_port)
# The "cu" (call-up) device has to be used for outgoing communication on MacOS
if sys.platform == "darwin" and "tty" in active_port:
active_port = [active_port, active_port.replace("tty", "cu")]
ports = list_ports.comports()
for p in ports:
if p.device in active_port:
return p.pid
print("\nFailed to get PID of a device on {}, using standard reset sequence.".format(active_port))
def bootloader_reset(self, usb_jtag_serial=False, extra_delay=False):
""" Issue a reset-to-bootloader, with USB-JTAG-Serial custom reset sequence option
"""
# RTS = either CH_PD/EN or nRESET (both active low = chip in reset)
# DTR = GPIO0 (active low = boot to flasher)
#
# DTR & RTS are active low signals,
# ie True = pin @ 0V, False = pin @ VCC.
if usb_jtag_serial:
# Custom reset sequence, which is required when the device
# is connecting via its USB-JTAG-Serial peripheral
self._setRTS(False)
self._setDTR(False) # Idle
time.sleep(0.1)
self._setDTR(True) # Set IO0
self._setRTS(False)
time.sleep(0.1)
self._setRTS(True) # Reset. Note dtr/rts calls inverted so we go through (1,1) instead of (0,0)
self._setDTR(False)
self._setRTS(True) # Extra RTS set for RTS as Windows only propagates DTR on RTS setting
time.sleep(0.1)
self._setDTR(False)
self._setRTS(False)
else:
# This fpga delay is for Espressif internal use
fpga_delay = True if self.FPGA_SLOW_BOOT and os.environ.get("ESPTOOL_ENV_FPGA", "").strip() == "1" else False
delay = 7 if fpga_delay else 0.5 if extra_delay else 0.05 # 0.5 needed for ESP32 rev0 and rev1
self._setDTR(False) # IO0=HIGH
self._setRTS(True) # EN=LOW, chip in reset
time.sleep(0.1)
self._setDTR(True) # IO0=LOW
self._setRTS(False) # EN=HIGH, chip out of reset
time.sleep(delay)
self._setDTR(False) # IO0=HIGH, done
def _connect_attempt(self, mode='default_reset', usb_jtag_serial=False, extra_delay=False):
""" A single connection attempt """
last_error = None
boot_log_detected = False
download_mode = False
# If we're doing no_sync, we're likely communicating as a pass through
# with an intermediate device to the ESP32
if mode == "no_reset_no_sync":
return last_error
if mode != 'no_reset':
if not self.USES_RFC2217: # Might block on rfc2217 ports
self._port.reset_input_buffer() # Empty serial buffer to isolate boot log
self.bootloader_reset(usb_jtag_serial, extra_delay)
# Detect the ROM boot log and check actual boot mode (ESP32 and later only)
waiting = self._port.inWaiting()
read_bytes = self._port.read(waiting)
data = re.search(b'boot:(0x[0-9a-fA-F]+)(.*waiting for download)?', read_bytes, re.DOTALL)
if data is not None:
boot_log_detected = True
boot_mode = data.group(1)
download_mode = data.group(2) is not None
for _ in range(5):
try:
self.flush_input()
self._port.flushOutput()
self.sync()
return None
except FatalError as e:
print('.', end='')
sys.stdout.flush()
time.sleep(0.05)
last_error = e
if boot_log_detected:
last_error = FatalError("Wrong boot mode detected ({})! The chip needs to be in download mode.".format(boot_mode.decode("utf-8")))
if download_mode:
last_error = FatalError("Download mode successfully detected, but getting no sync reply: The serial TX path seems to be down.")
return last_error
def get_memory_region(self, name):
""" Returns a tuple of (start, end) for the memory map entry with the given name, or None if it doesn't exist
"""
try:
return [(start, end) for (start, end, n) in self.MEMORY_MAP if n == name][0]
except IndexError:
return None
def connect(self, mode='default_reset', attempts=DEFAULT_CONNECT_ATTEMPTS, detecting=False, warnings=True):
""" Try connecting repeatedly until successful, or giving up """
if warnings and mode in ['no_reset', 'no_reset_no_sync']:
print('WARNING: Pre-connection option "{}" was selected.'.format(mode),
'Connection may fail if the chip is not in bootloader or flasher stub mode.')
print('Connecting...', end='')
sys.stdout.flush()
last_error = None
usb_jtag_serial = (mode == 'usb_reset') or (self._get_pid() == self.USB_JTAG_SERIAL_PID)
try:
for _, extra_delay in zip(range(attempts) if attempts > 0 else itertools.count(), itertools.cycle((False, True))):
last_error = self._connect_attempt(mode=mode, usb_jtag_serial=usb_jtag_serial, extra_delay=extra_delay)
if last_error is None:
break
finally:
print('') # end 'Connecting...' line
if last_error is not None:
raise FatalError('Failed to connect to {}: {}'
'\nFor troubleshooting steps visit: '
'https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html'.format(self.CHIP_NAME, last_error))
if not detecting:
try:
# check the date code registers match what we expect to see
chip_magic_value = self.read_reg(ESPLoader.CHIP_DETECT_MAGIC_REG_ADDR)
if chip_magic_value not in self.CHIP_DETECT_MAGIC_VALUE:
actually = None
for cls in [ESP8266ROM, ESP32ROM, ESP32S2ROM, ESP32S3BETA2ROM, ESP32S3ROM,
ESP32C3ROM, ESP32H2BETA1ROM, ESP32H2BETA2ROM, ESP32C2ROM, ESP32C6BETAROM]:
if chip_magic_value in cls.CHIP_DETECT_MAGIC_VALUE:
actually = cls
break
if warnings and actually is None:
print(("WARNING: This chip doesn't appear to be a %s (chip magic value 0x%08x). "
"Probably it is unsupported by this version of esptool.") % (self.CHIP_NAME, chip_magic_value))
else:
raise FatalError("This chip is %s not %s. Wrong --chip argument?" % (actually.CHIP_NAME, self.CHIP_NAME))
except UnsupportedCommandError:
self.secure_download_mode = True
self._post_connect()
self.check_chip_id()
def _post_connect(self):
"""
Additional initialization hook, may be overridden by the chip-specific class.
Gets called after connect, and after auto-detection.
"""
pass
def read_reg(self, addr, timeout=DEFAULT_TIMEOUT):
""" Read memory address in target """
# we don't call check_command here because read_reg() function is called
# when detecting chip type, and the way we check for success (STATUS_BYTES_LENGTH) is different
# for different chip types (!)
val, data = self.command(self.ESP_READ_REG, struct.pack('<I', addr), timeout=timeout)
if byte(data, 0) != 0:
raise FatalError.WithResult("Failed to read register address %08x" % addr, data)
return val
""" Write to memory address in target """
def write_reg(self, addr, value, mask=0xFFFFFFFF, delay_us=0, delay_after_us=0):
command = struct.pack('<IIII', addr, value, mask, delay_us)
if delay_after_us > 0:
# add a dummy write to a date register as an excuse to have a delay
command += struct.pack('<IIII', self.UART_DATE_REG_ADDR, 0, 0, delay_after_us)
return self.check_command("write target memory", self.ESP_WRITE_REG, command)
def update_reg(self, addr, mask, new_val):
""" Update register at 'addr', replace the bits masked out by 'mask'
with new_val. new_val is shifted left to match the LSB of 'mask'
Returns just-written value of register.
"""
shift = _mask_to_shift(mask)
val = self.read_reg(addr)
val &= ~mask
val |= (new_val << shift) & mask
self.write_reg(addr, val)
return val
""" Start downloading an application image to RAM """
def mem_begin(self, size, blocks, blocksize, offset):
if self.IS_STUB: # check we're not going to overwrite a running stub with this data
stub = self.STUB_CODE
load_start = offset
load_end = offset + size
for (start, end) in [(stub["data_start"], stub["data_start"] + len(stub["data"])),
(stub["text_start"], stub["text_start"] + len(stub["text"]))]:
if load_start < end and load_end > start:
raise FatalError(("Software loader is resident at 0x%08x-0x%08x. "
"Can't load binary at overlapping address range 0x%08x-0x%08x. "
"Either change binary loading address, or use the --no-stub "
"option to disable the software loader.") % (start, end, load_start, load_end))
return self.check_command("enter RAM download mode", self.ESP_MEM_BEGIN,
struct.pack('<IIII', size, blocks, blocksize, offset))
""" Send a block of an image to RAM """
def mem_block(self, data, seq):
return self.check_command("write to target RAM", self.ESP_MEM_DATA,
struct.pack('<IIII', len(data), seq, 0, 0) + data,
self.checksum(data))
""" Leave download mode and run the application """
def mem_finish(self, entrypoint=0):
# Sending ESP_MEM_END usually sends a correct response back, however sometimes
# (with ROM loader) the executed code may reset the UART or change the baud rate
# before the transmit FIFO is empty. So in these cases we set a short timeout and
# ignore errors.
timeout = DEFAULT_TIMEOUT if self.IS_STUB else MEM_END_ROM_TIMEOUT
data = struct.pack('<II', int(entrypoint == 0), entrypoint)
try:
return self.check_command("leave RAM download mode", self.ESP_MEM_END,
data=data, timeout=timeout)
except FatalError:
if self.IS_STUB:
raise
pass
""" Start downloading to Flash (performs an erase)
Returns number of blocks (of size self.FLASH_WRITE_SIZE) to write.
"""
def flash_begin(self, size, offset, begin_rom_encrypted=False):
num_blocks = (size + self.FLASH_WRITE_SIZE - 1) // self.FLASH_WRITE_SIZE
erase_size = self.get_erase_size(offset, size)
t = time.time()
if self.IS_STUB:
timeout = DEFAULT_TIMEOUT
else:
timeout = timeout_per_mb(ERASE_REGION_TIMEOUT_PER_MB, size) # ROM performs the erase up front
params = struct.pack('<IIII', erase_size, num_blocks, self.FLASH_WRITE_SIZE, offset)
if isinstance(self, (ESP32S2ROM, ESP32S3BETA2ROM, ESP32S3ROM, ESP32C3ROM,
ESP32C6BETAROM, ESP32H2BETA1ROM, ESP32C2ROM, ESP32H2BETA2ROM)) and not self.IS_STUB:
params += struct.pack('<I', 1 if begin_rom_encrypted else 0)
self.check_command("enter Flash download mode", self.ESP_FLASH_BEGIN,
params, timeout=timeout)
if size != 0 and not self.IS_STUB:
print("Took %.2fs to erase flash block" % (time.time() - t))
return num_blocks
""" Write block to flash """
def flash_block(self, data, seq, timeout=DEFAULT_TIMEOUT):
self.check_command("write to target Flash after seq %d" % seq,
self.ESP_FLASH_DATA,
struct.pack('<IIII', len(data), seq, 0, 0) + data,
self.checksum(data),
timeout=timeout)
""" Encrypt before writing to flash """
def flash_encrypt_block(self, data, seq, timeout=DEFAULT_TIMEOUT):
if isinstance(self, (ESP32S2ROM, ESP32C3ROM, ESP32S3ROM, ESP32H2BETA1ROM, ESP32C2ROM, ESP32H2BETA2ROM)) and not self.IS_STUB:
# ROM support performs the encrypted writes via the normal write command,
# triggered by flash_begin(begin_rom_encrypted=True)
return self.flash_block(data, seq, timeout)
self.check_command("Write encrypted to target Flash after seq %d" % seq,
self.ESP_FLASH_ENCRYPT_DATA,
struct.pack('<IIII', len(data), seq, 0, 0) + data,
self.checksum(data),
timeout=timeout)
""" Leave flash mode and run/reboot """
def flash_finish(self, reboot=False):
pkt = struct.pack('<I', int(not reboot))
# stub sends a reply to this command
self.check_command("leave Flash mode", self.ESP_FLASH_END, pkt)
""" Run application code in flash """
def run(self, reboot=False):
# Fake flash begin immediately followed by flash end
self.flash_begin(0, 0)
self.flash_finish(reboot)
""" Read SPI flash manufacturer and device id """
def flash_id(self):
SPIFLASH_RDID = 0x9F
return self.run_spiflash_command(SPIFLASH_RDID, b"", 24)
def get_security_info(self):
res = self.check_command('get security info', self.ESP_GET_SECURITY_INFO, b'')
esp32s2 = True if len(res) == 12 else False
res = struct.unpack("<IBBBBBBBB" if esp32s2 else "<IBBBBBBBBII", res)
return {
"flags": res[0],
"flash_crypt_cnt": res[1],
"key_purposes": res[2:9],
"chip_id": None if esp32s2 else res[9],
"api_version": None if esp32s2 else res[10],
}
@esp32s3_or_newer_function_only
def get_chip_id(self):
res = self.check_command('get security info', self.ESP_GET_SECURITY_INFO, b'')
res = struct.unpack("<IBBBBBBBBI", res[:16]) # 4b flags, 1b flash_crypt_cnt, 7*1b key_purposes, 4b chip_id
chip_id = res[9] # 2/4 status bytes invariant
return chip_id
@classmethod
def parse_flash_size_arg(cls, arg):
try:
return cls.FLASH_SIZES[arg]
except KeyError:
raise FatalError("Flash size '%s' is not supported by this chip type. Supported sizes: %s"
% (arg, ", ".join(cls.FLASH_SIZES.keys())))
@classmethod
def parse_flash_freq_arg(cls, arg):
try:
return cls.FLASH_FREQUENCY[arg]
except KeyError:
raise FatalError("Flash frequency '%s' is not supported by this chip type. Supported frequencies: %s"
% (arg, ", ".join(cls.FLASH_FREQUENCY.keys())))
def run_stub(self, stub=None):
if stub is None:
stub = self.STUB_CODE
if self.sync_stub_detected:
print("Stub is already running. No upload is necessary.")
return self.STUB_CLASS(self)
# Upload
print("Uploading stub...")
for field in ['text', 'data']:
if field in stub:
offs = stub[field + "_start"]
length = len(stub[field])
blocks = (length + self.ESP_RAM_BLOCK - 1) // self.ESP_RAM_BLOCK
self.mem_begin(length, blocks, self.ESP_RAM_BLOCK, offs)
for seq in range(blocks):
from_offs = seq * self.ESP_RAM_BLOCK
to_offs = from_offs + self.ESP_RAM_BLOCK
self.mem_block(stub[field][from_offs:to_offs], seq)
print("Running stub...")
self.mem_finish(stub['entry'])
p = self.read()
if p != b'OHAI':
raise FatalError("Failed to start stub. Unexpected response: %s" % p)
print("Stub running...")
return self.STUB_CLASS(self)
@stub_and_esp32_function_only
def flash_defl_begin(self, size, compsize, offset):
""" Start downloading compressed data to Flash (performs an erase)
Returns number of blocks (size self.FLASH_WRITE_SIZE) to write.
"""
num_blocks = (compsize + self.FLASH_WRITE_SIZE - 1) // self.FLASH_WRITE_SIZE
erase_blocks = (size + self.FLASH_WRITE_SIZE - 1) // self.FLASH_WRITE_SIZE
t = time.time()
if self.IS_STUB:
write_size = size # stub expects number of bytes here, manages erasing internally
timeout = DEFAULT_TIMEOUT
else:
write_size = erase_blocks * self.FLASH_WRITE_SIZE # ROM expects rounded up to erase block size
timeout = timeout_per_mb(ERASE_REGION_TIMEOUT_PER_MB, write_size) # ROM performs the erase up front
print("Compressed %d bytes to %d..." % (size, compsize))
params = struct.pack('<IIII', write_size, num_blocks, self.FLASH_WRITE_SIZE, offset)
if isinstance(self, (ESP32S2ROM, ESP32S3BETA2ROM, ESP32S3ROM, ESP32C3ROM,
ESP32C6BETAROM, ESP32H2BETA1ROM, ESP32C2ROM, ESP32H2BETA2ROM)) and not self.IS_STUB:
params += struct.pack('<I', 0) # extra param is to enter encrypted flash mode via ROM (not supported currently)
self.check_command("enter compressed flash mode", self.ESP_FLASH_DEFL_BEGIN, params, timeout=timeout)
if size != 0 and not self.IS_STUB:
# (stub erases as it writes, but ROM loaders erase on begin)
print("Took %.2fs to erase flash block" % (time.time() - t))
return num_blocks
""" Write block to flash, send compressed """
@stub_and_esp32_function_only
def flash_defl_block(self, data, seq, timeout=DEFAULT_TIMEOUT):
self.check_command("write compressed data to flash after seq %d" % seq,
self.ESP_FLASH_DEFL_DATA, struct.pack('<IIII', len(data), seq, 0, 0) + data, self.checksum(data), timeout=timeout)
""" Leave compressed flash mode and run/reboot """
@stub_and_esp32_function_only
def flash_defl_finish(self, reboot=False):
if not reboot and not self.IS_STUB:
# skip sending flash_finish to ROM loader, as this
# exits the bootloader. Stub doesn't do this.
return
pkt = struct.pack('<I', int(not reboot))
self.check_command("leave compressed flash mode", self.ESP_FLASH_DEFL_END, pkt)
self.in_bootloader = False
@stub_and_esp32_function_only
def flash_md5sum(self, addr, size):
# the MD5 command returns additional bytes in the standard
# command reply slot
timeout = timeout_per_mb(MD5_TIMEOUT_PER_MB, size)
res = self.check_command('calculate md5sum', self.ESP_SPI_FLASH_MD5, struct.pack('<IIII', addr, size, 0, 0),
timeout=timeout)
if len(res) == 32:
return res.decode("utf-8") # already hex formatted
elif len(res) == 16:
return hexify(res).lower()
else:
raise FatalError("MD5Sum command returned unexpected result: %r" % res)
@stub_and_esp32_function_only
def change_baud(self, baud):
print("Changing baud rate to %d" % baud)
# stub takes the new baud rate and the old one
second_arg = self._port.baudrate if self.IS_STUB else 0
self.command(self.ESP_CHANGE_BAUDRATE, struct.pack('<II', baud, second_arg))
print("Changed.")
self._set_port_baudrate(baud)
time.sleep(0.05) # get rid of crap sent during baud rate change
self.flush_input()
@stub_function_only
def erase_flash(self):
# depending on flash chip model the erase may take this long (maybe longer!)
self.check_command("erase flash", self.ESP_ERASE_FLASH,
timeout=CHIP_ERASE_TIMEOUT)
@stub_function_only
def erase_region(self, offset, size):
if offset % self.FLASH_SECTOR_SIZE != 0:
raise FatalError("Offset to erase from must be a multiple of 4096")
if size % self.FLASH_SECTOR_SIZE != 0:
raise FatalError("Size of data to erase must be a multiple of 4096")
timeout = timeout_per_mb(ERASE_REGION_TIMEOUT_PER_MB, size)
self.check_command("erase region", self.ESP_ERASE_REGION, struct.pack('<II', offset, size), timeout=timeout)
def read_flash_slow(self, offset, length, progress_fn):
raise NotImplementedInROMError(self, self.read_flash_slow)
def read_flash(self, offset, length, progress_fn=None):
if not self.IS_STUB:
return self.read_flash_slow(offset, length, progress_fn) # ROM-only routine
# issue a standard bootloader command to trigger the read
self.check_command("read flash", self.ESP_READ_FLASH,
struct.pack('<IIII',
offset,
length,
self.FLASH_SECTOR_SIZE,
64))
# now we expect (length // block_size) SLIP frames with the data