This module lets you log data to a MY_DATA file saved on a micro:bit V2 MICROBIT USB drive.
此模块允许你将数据记录到保存在 micro:bit 上的 MY_DATA 文件中 V2 MICROBIT USB 驱动器。

The data is structured in a table format and it can be viewed and plotted with a browser.
数据以表格格式构建，可以使用浏览器查看和绘制。

Further guidance on this feature can be found on the data logging page of the microbit.org website.
有关此功能的更多指导，请参阅 microbit.org 网站的 Data Logging 页面 。

Functions  函数 

Set up the log file header.
设置日志文件头。

This function accepts any number of positional arguments, each creates a column header, e.g. log.set_labels("X", "Y", "Z").
此函数接受任意数量的位置参数，每个参数创建一个列标题，例如 log.set_labels（“X”， “Y”， “Z”）。

Ideally this function should be called a single time, before any data is logged, to configure the data table header once.
理想情况下，在记录任何数据之前，应调用此函数一次，以配置数据表标头一次。

If a log file already exists when the programme starts, or if this function is called multiple times, it will check the labels already defined in the log file. If this function call contains any new labels not already present, it will generate a new header row with the additional columns.
如果程序启动时日志文件已经存在，或者如果此函数被多次调用，它将检查日志文件中已定义的标签。如果此函数调用包含任何尚不存在的新标签，它将生成一个包含其他列的新标题行。

By default the first column contains a time stamp for each row. The time unit can be selected via the timestamp argument, e.g. log.set_labels("temp", timestamp=log.MINUTES)
默认情况下，第一列包含每行的时间戳。时间单位可以通过 timestamp 参数选择，例如 log.set_labels("temp", timestamp=log.MINUTES)

• *labels – Any number of positional arguments, each corresponding to an entry in the log header.
  *labels – 任意数量的位置参数，每个参数对应于日志标头中的一个条目。

• timestamp – Select the timestamp unit that will be automatically added as the first column in every row. Timestamp values can be one of log.MILLISECONDS, log.SECONDS, log.MINUTES, log.HOURS, log.DAYS or None to disable the timestamp. The default value is log.SECONDS.
  timestamp （时间戳 ） – 选择将自动使用的时间戳单位 添加为每行的第一列。时间戳值可以是以下值之一 日志。MILLISECONDS， 对数。SECONDS 中， 对数。MINUTES， 日志。小时 ， 日志。DAYS 或 None 禁用时间戳。默认值为 log。秒。

Configure mirroring of the data logging activity to the serial output.
配置将数据记录活动镜像到串行输出。

Serial mirroring is disabled by default. When enabled, it will print to serial each row logged into the log file.
默认情况下，串行镜像处于禁用状态。启用后，它将打印以序列化登录到日志文件中的每一行。

serial – True enables mirroring data to the serial output.
serial – True 允许将数据镜像到串行输出。

Delete the contents of the log, including headers.
删除日志的内容，包括标头。

To add the log headers again the set_labels function should to be called after this function.
要再次添加日志标头，应在此函数之后调用 set_labels 函数。

There are two erase modes; “full” completely removes the data from the physical storage, and “fast” invalidates the data without removing it.
有两种擦除模式;“full” 从物理存储中完全删除数据，而 “fast” 使数据无效而不删除数据。

full – True selects a “full” erase and False selects the “fast” erase method.
full – True 选择“完全”擦除，False 选择“快速”擦除方法。

Add a data row to the log.
向日志中添加数据行。

There are two ways to log data with this function:
使用此函数有两种记录数据的方法：

1. Via keyword arguments, each argument name representing a label.
   通过关键字参数，每个参数名称代表一个标签。

   • e.g. log.add(X=compass.get_x(), Y=compass.get_y())   log.add(X=compass.get_x(), Y=compass.get_y()) 例如

2. Via a dictionary, each dictionary key representing a label.
   通过字典，每个字典键代表一个标签。

   • e.g. log.add({ "X": compass.get_x(), "Y": compass.get_y() })   log.add({ "X": compass.get_x(), "Y": compass.get_y() }) 例如

The keyword argument option can be easier to use, and the dictionary option allows the use of spaces (and other special characters), that could not be used with the keyword arguments.
keyword argument 选项可能更易于使用，而 dictionary 选项允许使用无法与 keyword 参数一起使用的空格（和其他特殊字符）。

New labels not previously specified via the set_labels function, or by a previous call to this function, will trigger a new header entry to be added to the log with the extra labels.
之前未通过 set_labels 函数或之前调用此函数指定的新标签将触发一个新的 Headers 条目，以添加到包含额外标签的日志中。

Labels previously specified and not present in a call to this function will be skipped with an empty value in the log row.
以前指定但未出现在对此函数的调用中的标签将被跳过，并在日志行中为空值。

OSError – When the log is full this function raises an OSError exception with error code 28 ENOSPC, which indicates there is no space left in the device.
OSError – 当日志已满时，此函数会引发 OSError 错误代码为 28 ENOSPC 的异常，这表示设备中没有剩余空间。

Examples  示例 

A minimal example:  一个最小的示例：

from microbit import *
import log

# Set the timer to log data every 5 seconds
@run_every(s=5)
def log_temp():
    log.add(temp=temperature())

while True:
    # Needed so that the programme doesn't end
    sleep(100)

一个贯穿日志模块 API 的所有功能的示例：

from microbit import *
import log

# Configure the labels and select a time unit for the timestamp
log.set_labels('temp', 'brightness', timestamp=log.SECONDS)

# Send each data row to the serial output
log.set_mirroring(True)

continue_logging = True

# This decorator schedules this function to run every 10s 50ms
@run_every(s=10, ms=50)
def log_data():
    """Log the temperature and light level, and display an icon."""
    global continue_logging
    if continue_logging:
        display.show(Image.SURPRISED)
        try:
            log.add(temp=temperature(), brightness=display.read_light_level())
        except OSError:
            continue_logging = False
            display.scroll("Log full")
        sleep(500)

while True:
    if button_a.is_pressed() and button_b.is_pressed():
        display.show(Image.CONFUSED)
        # Delete the log file using the "full" options, which takes
        # longer but ensures the data is wiped from the device
        log.delete(full=True)
        continue_logging = True
    elif button_a.is_pressed():
        display.show(Image.HAPPY)
        # Log only the light level, the temp entry will be empty. If the log
        # is full this will throw an exception and the programme will stop
        log.add({
            "brightness": display.read_light_level()
        })
    else:
        display.show(Image.ASLEEP)
    sleep(500)