blob: 74c07cfa81a433f446470672f04a17721d69a999 [file] [log] [blame]
#!/usr/bin/env python3
# Copyright (c) 2020 Project CHIP Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Flash an ESP32 device.
This is layered so that a caller can perform individual operations
through an `Flasher` instance, or operations according to a command line.
For `Flasher`, see the class documentation. For the parse_command()
interface or standalone execution:
usage: esp32_firmware_utils.py [-h] [--verbose] [--erase] [--application FILE]
[--verify_application] [--reset] [--skip_reset]
[--esptool FILE] [--parttool FILE]
[--sdkconfig FILE] [--chip CHIP] [--port PORT]
[--baud BAUD] [--before ACTION]
[--after ACTION] [--flash_mode MODE]
[--flash_freq FREQ] [--flash_size SIZE]
[--compress] [--bootloader FILE]
[--bootloader_offset OFFSET] [--partition FILE]
[--partition_offset OFFSET]
[--application_offset OFFSET]
Flash ESP32 device
optional arguments:
-h, --help show this help message and exit
configuration:
--verbose, -v Report more verbosely
--esptool FILE File name of the esptool executable
--parttool FILE File name of the parttool executable
--sdkconfig FILE File containing option defaults
--chip CHIP Target chip type
--port PORT Serial port device
--baud BAUD Serial port baud rate
--before ACTION What to do before connecting
--after ACTION What to do when finished
--flash_mode MODE, --flash-mode MODE
Flash mode
--flash_freq FREQ, --flash-freq FREQ
Flash frequency
--flash_size SIZE, --flash-size SIZE
Flash size
--compress, -z Compress data in transfer
--bootloader FILE Bootloader image
--bootloader_offset OFFSET, --bootloader-offset OFFSET
Bootloader offset
--partition FILE Partition table image
--partition_offset OFFSET, --partition-offset OFFSET
Partition table offset
--application_offset OFFSET, --application-offset OFFSET
Application offset
operations:
--erase Erase device
--application FILE Flash an image
--verify_application, --verify-application
Verify the image after flashing
--reset Reset device after flashing
--skip_reset, --skip-reset
Do not reset device after flashing
"""
import os
import pathlib
import sys
import firmware_utils
# Additional options that can be use to configure an `Flasher`
# object (as dictionary keys) and/or passed as command line options.
ESP32_OPTIONS = {
# Configuration options define properties used in flashing operations.
'configuration': {
# Tool configuration options.
'esptool': {
'help': 'File name of the esptool executable',
'default': 'esptool.py',
'argparse': {
'metavar': 'FILE',
},
'command': [
{'option': 'esptool'},
{'optional': 'port'},
{'optional': 'baud'},
{'optional': 'before'},
{'optional': 'after'},
()
],
'verify': ['{esptool}', 'version'],
'error':
"""\
Unable to execute {esptool}.
Please ensure that the esptool Python package is available.
See the ESP32 setup guide for instructions.
""",
},
'parttool': {
'help': 'File name of the parttool executable',
'default': None,
'argparse': {
'metavar': 'FILE'
},
'command': [
{'option': 'parttool'},
{'optional': 'port'},
{'optional': 'baud'},
{
'option': 'partition',
'result': ['--partition-table-file', '{partition}'],
'expand': True
},
()
],
'verify': ['{parttool}', '--quiet'],
'error':
"""\
Unable to execute {parttool}.
Please ensure that this tool is installed and
that $IDF_PATH is set. See the ESP32 example
README for installation instructions.
""",
},
'sdkconfig': {
'help': 'File containing option defaults',
'default': None,
'argparse': {
'metavar': 'FILE'
},
},
# Device configuration options.
'chip': {
'help': 'Target chip type',
'default': 'esp32',
'argparse': {
'metavar': 'CHIP'
},
'sdkconfig': 'CONFIG_IDF_TARGET',
},
'port': {
'help': 'Serial port device',
'default': None,
'argparse': {
'metavar': 'PORT',
},
'sdkconfig': 'CONFIG_ESPTOOLPY_PORT',
},
'baud': {
'help': 'Serial port baud rate',
'default': None,
'argparse': {
'metavar': 'BAUD',
},
'sdkconfig': 'CONFIG_ESPTOOLPY_BAUD',
},
'before': {
'help': 'What to do before connecting',
'default': None,
'argparse': {
'metavar': 'ACTION',
},
'sdkconfig': 'CONFIG_ESPTOOLPY_BEFORE',
},
'after': {
'help': 'What to do when finished',
'default': None,
'argparse': {
'metavar': 'ACTION',
},
'sdkconfig': 'CONFIG_ESPTOOLPY_AFTER',
},
'flash_mode': {
'help': 'Flash mode',
'default': None,
'argparse': {
'metavar': 'MODE',
},
'sdkconfig': 'CONFIG_ESPTOOLPY_FLASHMODE',
},
'flash_freq': {
'help': 'Flash frequency',
'default': None,
'argparse': {
'metavar': 'FREQ',
},
'sdkconfig': 'CONFIG_ESPTOOLPY_FLASHFREQ',
},
'flash_size': {
'help': 'Flash size',
'default': None,
'argparse': {
'metavar': 'SIZE',
},
'sdkconfig': 'CONFIG_ESPTOOLPY_FLASHSIZE',
},
'compress': {
'help': 'Compress data in transfer',
'default': None,
'alias': ['-z'],
'argparse': {
'action': 'store_true'
},
'sdkconfig': 'CONFIG_ESPTOOLPY_COMPRESSED',
},
# Flashing things.
'bootloader': {
'help': 'Bootloader image',
'default': None,
'argparse': {
'metavar': 'FILE',
'type': pathlib.Path,
},
},
'bootloader_offset': {
'help': 'Bootloader offset',
'default': '0x1000',
'argparse': {
'metavar': 'OFFSET'
},
'sdkconfig': 'CONFIG_BOOTLOADER_OFFSET_IN_FLASH',
},
'partition': {
'help': 'Partition table image',
'default': None,
'argparse': {
'metavar': 'FILE',
'type': pathlib.Path,
},
},
'partition_offset': {
'help': 'Partition table offset',
'default': None,
'argparse': {
'metavar': 'OFFSET'
},
'sdkconfig': 'CONFIG_PARTITION_TABLE_OFFSET',
},
'application_offset': {
'help': 'Application offset',
'default': None,
'argparse': {
'metavar': 'OFFSET'
},
},
},
}
def namespace_defaults(dst, src):
for key, value in src.items():
if key not in dst or getattr(dst, key) is None:
setattr(dst, key, value)
class Flasher(firmware_utils.Flasher):
"""Manage esp32 flashing."""
def __init__(self, **options):
super().__init__(platform='ESP32', module=__name__, **options)
self.define_options(ESP32_OPTIONS)
def _postprocess_argv(self):
if self.option.sdkconfig:
namespace_defaults(self.option,
self.read_sdkconfig(self.option.sdkconfig))
# idf = os.environ.get('IDF_PATH')
# if idf:
# if self.option.esptool is None:
# self.option.esptool = os.path.join(
# idf,
# 'components/esptool_py/esptool/esptool.py')
# if self.option.parttool is None:
# self.option.parttool = os.path.join(
# idf,
# 'components/partition_table/parttool.py')
def read_sdkconfig(self, filename):
"""Given an ESP32 sdkconfig file, read it for values of options
not otherwise set.
"""
config_map = {}
for key, info in vars(self.info).items():
config_key = info.get('sdkconfig')
if config_key:
config_map[config_key] = key
result = {}
with open(filename) as f:
for line in f:
k, eq, v = line.strip().partition('=')
if eq == '=' and k in config_map:
result[config_map[k]] = v.strip('"')
return result
IDF_PATH_TOOLS = {
'parttool': 'components/partition_table/parttool.py',
}
def locate_tool(self, tool):
if tool in self.IDF_PATH_TOOLS:
idf_path = os.environ.get('IDF_PATH')
if idf_path:
return os.path.join(idf_path, self.IDF_PATH_TOOLS[tool])
return super().locate_tool(tool)
# Common command line arguments for esptool flashing subcommands.
FLASH_ARGUMENTS = [
{'optional': 'flash_mode'},
{'optional': 'flash_freq'},
{'optional': 'flash_size'},
{
'match': '{compress}',
'test': [(True, '-z'), ('y', '-z')],
'default': '-u'
},
]
def erase(self):
"""Perform `commander device masserase`."""
return self.run_tool('esptool', ['erase_flash'], {}, 'Erase device')
def verify(self, image, address=0):
"""Verify image(s)."""
if not isinstance(image, list):
image = [address, image]
return self.run_tool(
'esptool',
['verify_flash', self.FLASH_ARGUMENTS, image],
name='Verify',
pass_message='Verified',
fail_message='Not verified',
fail_level=2)
def flash(self, image, address=0):
"""Flash image(s)."""
if not isinstance(image, list):
image = [address, image]
return self.run_tool(
'esptool',
['write_flash', self.FLASH_ARGUMENTS, image],
name='Flash')
PARTITION_INFO = {
'phy': ['--partition-type', 'data', '--partition-subtype', 'phy'],
'application': ['--partition-boot-default'],
'ota': ['--partition-type', 'data', '--partition-subtype', 'ota'],
'factory': [
'--partition-type', 'app', '--partition-subtype', 'factory'
],
}
def get_partition_info(self, item, info, options=None):
"""Run parttool to get partition information."""
return self.run_tool(
'parttool',
['get_partition_info', self.PARTITION_INFO[item], '--info', info],
options or {},
capture_output=True).stdout.strip()
def make_wrapper(self, argv):
self.parser.add_argument(
'--use-parttool',
metavar='FILENAME',
help='partition tool to configure flashing script')
self.parser.add_argument(
'--use-partition-file',
metavar='FILENAME',
help='partition file to configure flashing script')
self.parser.add_argument(
'--use-sdkconfig',
metavar='FILENAME',
help='sdkconfig to configure flashing script')
super().make_wrapper(argv)
def _platform_wrapper_args(self, args):
if args.use_sdkconfig:
# Include values from sdkconfig so that it isn't needed at
# flashing time.
namespace_defaults(args, self.read_sdkconfig(args.use_sdkconfig))
parttool = args.use_parttool or args.parttool
partfile = args.use_partition_file or args.partition
if parttool and partfile:
# Get unspecified offsets from the partition file now,
# so that parttool isn't needed at flashing time.
if args.application and args.application_offset is None:
args.application_offset = self.get_partition_info(
'application', 'offset',
{'parttool': parttool, 'partition': partfile})
def actions(self):
"""Perform actions on the device according to self.option."""
self.log(3, 'Options:', self.option)
if self.option.erase:
if self.erase().err:
return self
if self.option.application:
application = self.option.application
bootloader = self.option.bootloader
partition = self.option.partition
# Collect the flashable items.
flash = []
if bootloader:
flash += [self.option.bootloader_offset, bootloader]
if application:
offset = self.option.application_offset
if offset is None:
offset = self.get_partition_info('application', 'offset')
flash += [offset, application]
if partition:
flash += [self.option.partition_offset, partition]
# esptool.py doesn't have an independent reset command, so we add
# an `--after` option to the final operation, which may be either
# flash or verify.
if self.option.after is None:
if self.option.reset or self.option.reset is None:
self.option.after = 'hard_reset'
else:
self.option.after = 'no_reset'
if self.option.verify_application:
verify_after = self.option.after
self.option.after = 'no_reset'
if self.flash(flash).err:
return self
if self.option.verify_application:
self.option.after = verify_after
if self.verify(flash).err:
return self
return self
# Mobly integration
class ESP32Platform:
def __init__(self, flasher_args):
self.flasher = Flasher(**flasher_args)
def flash(self):
self.flasher.flash_command([os.getcwd()])
def verify_platform_args(platform_args):
required_args = [
'application',
'parttool',
'port',
'baud',
'before',
'after',
'flash_mode',
'flash_freq',
'flash_size',
'compress',
'bootloader',
'partition',
'partition_offset',
'application_offset',
]
difference = set(required_args) - set(platform_args)
if difference:
raise ValueError("Required arguments missing: %s" % difference)
def create_platform(platform_args):
verify_platform_args(platform_args[0])
return ESP32Platform(platform_args[0])
# End of Mobly integration
if __name__ == '__main__':
sys.exit(Flasher().flash_command(sys.argv))