def set_brick_name(self, name):
"""Set brick name.
:param str name: New brick name.
"""
tgram = Telegram(Opcode.SYSTEM_SETBRICKNAME)
tgram.add_string(15, name)
self._cmd(tgram)
def start_program(self, name):
"""Start a program on the brick.
:param str name: Program file name (example: ``"myprogram.rxe"``).
"""
tgram = Telegram(Opcode.DIRECT_START_PROGRAM)
tgram.add_filename(name)
self._cmd(tgram)
def keep_alive(self):
"""Reset the brick standby timer.
:return: Sleep timeout in milliseconds.
:rtype: int
"""
tgram = Telegram(Opcode.DIRECT_KEEP_ALIVE)
tgram = self._cmd(tgram)
sleep_timeout = tgram.parse_u32()
return sleep_timeout
def get_battery_level(self):
"""Get brick battery voltage.
:return: Battery voltage in millivolt.
:rtype: int
"""
tgram = Telegram(Opcode.DIRECT_GET_BATT_LVL)
tgram = self._cmd(tgram)
millivolts = tgram.parse_u16()
return millivolts
def blue_messenger(brick, message): tgram = Telegram(True, 0x09, False) tgram.add_u8(0) tgram.add_u8(len(message) + 1) tgram.add_string(len(message), message) tgram.add_u8(0) brick.sock.send(str(tgram))
def get_current_program_name(self):
"""Return name of program currently running on the brick.
:return: Program file name
:rtype: str
:raises nxt.error.DirectProtocolError: When no program is running.
"""
tgram = Telegram(Opcode.DIRECT_GET_CURR_PROGRAM)
tgram = self._cmd(tgram)
name = tgram.parse_filename()
return name
def reset_input_scaled_value(self, port):
"""Reset scaled value for an input port on the brick.
:param nxt.sensor.Port port: Input port identifier.
This can be used to reset accumulated value for some sensor modes.
.. warning:: This is a low level function, prefer to use a :mod:`nxt.sensor`
class.
"""
tgram = Telegram(Opcode.DIRECT_RESET_IN_VAL)
tgram.add_u8(port.value)
self._cmd(tgram)
def file_delete(self, name):
"""Delete a file on the brick.
:param str name: File name.
:return: The deleted file name.
:rtype: str
:raises nxt.error.FileNotFoundError: When file does not exists.
"""
tgram = Telegram(Opcode.SYSTEM_DELETE)
tgram.add_filename(name)
tgram = self._cmd(tgram)
name = tgram.parse_filename()
return name
def message_write(self, inbox, message):
"""Send a message to a brick mailbox.
:param int inbox: Mailbox number (0 to 19).
:param bytes message: Message to send (58 bytes maximum).
"""
if len(message) > 58:
raise ValueError("message too long")
tgram = Telegram(Opcode.DIRECT_MESSAGE_WRITE)
tgram.add_u8(inbox)
tgram.add_u8(len(message) + 1)
tgram.add_bytes(message)
tgram.add_u8(0)
self._cmd(tgram)
def file_close(self, handle):
"""Close open file.
:param int handle: Open file handle.
:return: The closed file handle.
:rtype: int
.. warning:: This is a low level function, prefer to use :meth:`open_file`.
"""
tgram = Telegram(Opcode.SYSTEM_CLOSE)
tgram.add_u8(handle)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
return handle
def module_close(self, handle):
"""Close module search.
:param int handle: Open module handle.
:return: The closed module handle.
:rtype: int
.. warning:: This is a low level function, prefer to use :meth:`find_modules`.
"""
tgram = Telegram(Opcode.SYSTEM_CLOSEMODHANDLE)
tgram.add_u8(handle)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
return handle
def stop_program(self):
"""Stop the running program on the brick.
:raises nxt.error.DirectProtocolError: When no program is running.
"""
tgram = Telegram(Opcode.DIRECT_STOP_PROGRAM)
self._cmd(tgram)
def bluetooth_factory_reset(self):
"""Reset brick Bluetooth to factory settings.
This only works on USB connection.
"""
tgram = Telegram(Opcode.SYSTEM_BTFACTORYRESET)
self._cmd(tgram)
def get_firmware_version(self):
"""Get firmware version information.
:return: Protocol and firmware versions, as two tuples with major and minor for
each version.
:rtype: ((int, int), (int, int))
"""
tgram = Telegram(Opcode.SYSTEM_VERSIONS)
tgram = self._cmd(tgram)
prot_minor = tgram.parse_u8()
prot_major = tgram.parse_u8()
prot_version = (prot_major, prot_minor)
fw_minor = tgram.parse_u8()
fw_major = tgram.parse_u8()
fw_version = (fw_major, fw_minor)
return prot_version, fw_version
def _cmd(self, tgram):
"""Send a message to the NXT brick and read reply.
:param nxt.telegram.Telegram tgram: Message to send.
:return: Reply message after status has been checked, or None if no reply
requested.
:rtype: nxt.telegram.Telegram or None
"""
reply_tgram = None
with self._lock:
self._sock.send(tgram.bytes())
if tgram.reply_req:
reply_tgram = Telegram(opcode=tgram.opcode,
pkt=self._sock.recv())
if reply_tgram:
reply_tgram.check_status()
return reply_tgram
def ls_get_status(self, port):
"""Get status of last low-speed transaction to a brick input port.
:param nxt.sensor.Port port: Input port identifier.
:return: Number of bytes to read as a result of the transaction.
:rtype: int
:raises nxt.error.I2CPendingError: When transaction is still in progress.
:raises nxt.error.DirectProtocolError: When there is an error on the bus.
.. warning:: This is a low level function, prefer to use a :mod:`nxt.sensor`
class.
"""
tgram = Telegram(Opcode.DIRECT_LS_GET_STATUS)
tgram.add_u8(port.value)
tgram = self._cmd(tgram)
size = tgram.parse_u8()
return size
def poll(self, *args, **kwargs):
ogram = poll_func(opcode, *args, **kwargs)
with self.lock:
self.sock.send(ogram.bytes())
if ogram.reply:
igram = Telegram(opcode=opcode, pkt=self.sock.recv())
if ogram.reply:
return parse_func(igram)
else:
return None
def ls_write(self, port, tx_data, rx_bytes):
"""Write data to a brick input port using low speed transaction.
:param nxt.sensor.Port port: Input port identifier.
:param bytes tx_data: Data to send.
:param int rx_bytes: Number of bytes to receive.
Function returns immediately. Transaction status can be retrieved using
:meth:`ls_get_status` and result must be read using :meth:`ls_read`.
.. warning:: This is a low level function, prefer to use a :mod:`nxt.sensor`
class.
"""
tgram = Telegram(Opcode.DIRECT_LS_WRITE)
tgram.add_u8(port.value)
tgram.add_u8(len(tx_data))
tgram.add_u8(rx_bytes)
tgram.add_bytes(tx_data)
self._cmd(tgram)
def poll_command(self, buf_num, size):
"""Get bytes from brick poll buffer.
:param int buf_num: Buffer number, 0 for USB, 1 for high speed.
:param int size: Number of bytes to read.
:return: Buffer number and read bytes.
:rtype: (int, bytes)
"""
tgram = Telegram(Opcode.SYSTEM_POLLCMD)
tgram.add_u8(buf_num)
tgram.add_u8(size)
tgram = self._cmd(tgram)
buf_num = tgram.parse_u8()
size = tgram.parse_u8()
command = tgram.parse_bytes(size)
return buf_num, command
def file_read(self, handle, size):
"""Read data from open file.
:param int handle: Open file handle.
:param int size: Number of bytes to read.
:return: The file handle and the read data.
:rtype: (int, bytes)
.. warning:: This is a low level function, prefer to use :meth:`open_file`.
"""
tgram = Telegram(Opcode.SYSTEM_READ)
tgram.add_u8(handle)
tgram.add_u16(size)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
size = tgram.parse_u16()
data = tgram.parse_bytes(size)
return handle, data
def module_find_next(self, handle):
"""Continue finding modules.
:param int handle: Handle open with :meth:`module_find_first`.
:return: The handle, next module found name, identifier, size and IO map size.
:rtype: (int, str, int, int, int)
:raises nxt.error.ModuleNotFoundError: When no more module is found.
.. warning:: This is a low level function, prefer to use :meth:`find_modules`.
"""
tgram = Telegram(Opcode.SYSTEM_FINDNEXTMODULE)
tgram.add_u8(handle)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
name = tgram.parse_filename()
mod_id = tgram.parse_u32()
mod_size = tgram.parse_u32()
mod_iomap_size = tgram.parse_u16()
return handle, name, mod_id, mod_size, mod_iomap_size
def module_find_first(self, pattern):
"""Start finding modules matching a pattern.
:param str pattern: Pattern to match modules against.
:return: A handle for the search, first module found name, identifier, size and
IO map size.
:rtype: (int, str, int, int, int)
:raises nxt.error.ModuleNotFoundError: When no module is found.
.. warning:: This is a low level function, prefer to use :meth:`find_modules`.
"""
tgram = Telegram(Opcode.SYSTEM_FINDFIRSTMODULE)
tgram.add_filename(pattern)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
name = tgram.parse_filename()
mod_id = tgram.parse_u32()
mod_size = tgram.parse_u32()
mod_iomap_size = tgram.parse_u16()
return handle, name, mod_id, mod_size, mod_iomap_size
def boot(self, *, sure=False):
"""Erase NXT brick firmware and go to SAM-BA boot mode.
:param bool sure: Set to ``True`` if you are really sure. Must be a keyword
parameter.
:return: Brick response, should be ``"Yes\0"``.
:rtype: bytes
This only works on USB connection.
.. danger:: This **erases the firmware** of the brick, you need to send a new
firmware to use it. Sending a firmware is not supported by NXT-Python. You
can use the original LEGO software or `libnxt`_ for example. Be sure to know
what you are doing.
.. _libnxt: https://git.ni.fr.eu.org/libnxt.git/
"""
if not sure:
raise ValueError("this is dangerous, please read documentation")
tgram = Telegram(Opcode.SYSTEM_BOOTCMD)
tgram.add_bytes(b"Let's dance: SAMBA\0")
tgram = self._cmd(tgram)
resp = tgram.parse_bytes()
return resp
def file_write(self, handle, data):
"""Write data to open file.
:param int handle: Open file handle.
:param bytes data: Data to write.
:return: The file handle and the number of bytes written.
:rtype: (int, int)
.. warning:: This is a low level function, prefer to use :meth:`open_file`.
"""
tgram = Telegram(Opcode.SYSTEM_WRITE)
tgram.add_u8(handle)
tgram.add_bytes(data)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
size = tgram.parse_u16()
return handle, size
def play_sound_file(self, loop, name):
"""Play a sound file on the brick.
:param bool loop: Loop mode, play continuously.
:param str name: Sound file name.
"""
tgram = Telegram(Opcode.DIRECT_PLAY_SOUND_FILE, reply_req=False)
tgram.add_bool(loop)
tgram.add_filename(name)
self._cmd(tgram)
def poll_command_length(self, buf_num):
"""Get number of bytes available in brick poll buffer.
:param int buf_num: Buffer number, 0 for USB, 1 for high speed.
:return: Buffer number and number of available bytes.
:rtype: (int, int)
"""
tgram = Telegram(Opcode.SYSTEM_POLLCMDLEN)
tgram.add_u8(buf_num)
tgram = self._cmd(tgram)
buf_num = tgram.parse_u8()
size = tgram.parse_u8()
return buf_num, size
def play_tone(self, frequency_hz, duration_ms):
"""Play a tone on the brick, do not wait until finished.
:param int frequency_hz: Tone frequency in Hertz.
:param int duration_ms: Tone duration in milliseconds.
This function do not wait until finished, if you want to play several notes, you
may need :func:`play_tone_and_wait`.
"""
tgram = Telegram(Opcode.DIRECT_PLAY_TONE, reply_req=False)
tgram.add_u16(frequency_hz)
tgram.add_u16(duration_ms)
self._cmd(tgram)
def file_find_next(self, handle):
"""Continue finding files.
:param int handle: Handle open with :meth:`file_find_first`.
:return: The handle, next file found name and size.
:rtype: (int, str, int)
:raises nxt.error.FileNotFoundError: When no more file is found.
.. warning:: This is a low level function, prefer to use :meth:`find_files`.
"""
tgram = Telegram(Opcode.SYSTEM_FINDNEXT)
tgram.add_u8(handle)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
name = tgram.parse_filename()
size = tgram.parse_u32()
return handle, name, size
def file_find_first(self, pattern):
"""Start finding files matching a pattern.
:param str pattern: Pattern to match files against.
:return: A handle for the search, first file found name and size.
:rtype: (int, str, int)
:raises nxt.error.FileNotFoundError: When no file is found.
.. warning:: This is a low level function, prefer to use :meth:`find_files`.
"""
tgram = Telegram(Opcode.SYSTEM_FINDFIRST)
tgram.add_filename(pattern)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
name = tgram.parse_filename()
size = tgram.parse_u32()
return handle, name, size
def reset_motor_position(self, port, relative):
"""Reset block or program motor position for a brick output port.
:param nxt.motor.Port port: Output port identifier.
:param bool relative: If ``True``, reset block position, if ``False``, reset
program position.
.. warning:: This is a low level function, prefer to use
:meth:`nxt.motor.Motor`, you can get one from :meth:`get_motor`.
"""
tgram = Telegram(Opcode.DIRECT_RESET_POSITION)
tgram.add_u8(port.value)
tgram.add_bool(relative)
self._cmd(tgram)
def file_open_write(self, name, size):
"""Open file for writing.
:param str name: File name.
:param int size: Final file size.
:return: The file handle.
:rtype: int
:raises nxt.error.FileExistsError: When file already exists.
:raises nxt.error.SystemProtocolError: When no space is available.
.. warning:: This is a low level function, prefer to use :meth:`open_file`.
"""
tgram = Telegram(Opcode.SYSTEM_OPENWRITE)
tgram.add_filename(name)
tgram.add_u32(size)
tgram = self._cmd(tgram)
handle = tgram.parse_u8()
return handle
