Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Generate a hub API from a dump. #7

Open
1 of 7 tasks
gpdaniels opened this issue Nov 20, 2020 · 13 comments
Open
1 of 7 tasks

Generate a hub API from a dump. #7

gpdaniels opened this issue Nov 20, 2020 · 13 comments
Assignees
@gpdaniels
Labels
enhancement New feature or request project - simulator For issues about the hub simulator

Comments

@gpdaniels
Copy link
Owner

gpdaniels commented Nov 20, 2020 •
edited
Loading

Using the dump-api.py script from the simulator it's possible to get what I hope is all the functions available on the hub (along with lots of other information)

What is needed:

  • See if it possible to determine all the built in modules, help("modules") prints to stdout, but on the hub this cannot be redirected because the micropython version is too old.
  • Extract recursively hub modules/classes/functions/variables.
  • Search the hub filesystem for any further modules/classes/functions.
  • Determine the arguments to all these modules/classes/functions (I think the mpy tool might be able to help with some).
  • Extract the values of all variables discovered.
  • Generate stub (or filled if possible) modules/classes/functions/variables for all functions on the hub.
  • Link remaining functions to the simulator virtual hub API.
@gpdaniels gpdaniels added the project - simulator For issues about the hub simulator label Nov 20, 2020
@gpdaniels gpdaniels self-assigned this Nov 20, 2020
@gpdaniels gpdaniels added the enhancement New feature or request label Nov 20, 2020
@pitust
Copy link
Contributor

pitust commented Dec 26, 2020 •
edited
Loading

i made a functioning disassembler for micropython. Should i post is somewhere in this repo or put it somewhere else? It can be used to disassemble correctly all of hub_runtime.mpy.

@gpdaniels
Copy link
Owner Author

😲 Wow that's amazing!

I'm more than happy to add it to this repo or just add links to your repo, is it written in python?

I was at some point going to add a decompiler directory to the top level of this repo for this kind of work. At some point I'll also add the experiments I've been doing trying to extract useful information from the hub firmware files.

@pitust
Copy link
Contributor

pitust commented Dec 26, 2020

It is written in typescript, not in python, but it depends on some micropython source files... Yes, it is an absolute mess.

@pitust
Copy link
Contributor

pitust commented Dec 26, 2020

See #10

@4doom4
Copy link

4doom4 commented Dec 30, 2020

Is there a list of all functions somewhere? I manually tried to call each function and recorded what they did and how to call them.

@gpdaniels
Copy link
Owner Author

There's the official documentation which has some of the functions in it, but not most.

I've been using this dump-api.py script to extract information from the hub, but the limited ram on the hub makes it harder than it needs to be. Also there's no way of determining the arguments of the functions or classes from the dump.

A better approach would probably be to decompile the files and extract the functions and their argument counts / named arguments. However, this won't get the functions that are baked into the firmware, so something needs to be done about that too.

TLDR: Nope, no list of functions yet.

@pitust
Copy link
Contributor

pitust commented Dec 31, 2020

Just to add to this, the internal hub module is actually native code and written in C.

@4doom4
Copy link

4doom4 commented Jan 2, 2021

if you want I could paste somewhere my function reference when I am done. I am currently a bit stuck in the async part with VirtualMachine from runtime. I am trying to run code async but even though asyncio seems to be there somehow I am not sure how to control it

@gpdaniels
Copy link
Owner Author

Sounds good, there's also a goal to add the official api docs here: #9 which I have yet to get to.

@4doom4
Copy link

4doom4 commented Jan 3, 2021 •
edited
Loading

This is what I have so far. I will continue to post here:

hub
	BT_VCP() - returns BT_VCP(0)
		any - ???
		close - ???
		read - ???
		readinto - ???
		readline - ???
		send - ???
		write - ???
		__bases__ - ???
		__del__ - ???
		callback - ???
		isconnected - ???
		readlines - ???
		recv - ???
		setinterrupt
	Image(image str) / () - returns Image object of image str i.e. '00090:09020:' or empty image object
		ALL_ARROWS - pre-defined image on 5x5 display
		ALL_CLOCKS - pre-defined image on 5x5 display
		ANGRY - pre-defined image on 5x5 display
		ARROW_E - pre-defined image on 5x5 display
		ARROW_N - pre-defined image on 5x5 display
		ARROW_NE - pre-defined image on 5x5 display
		ARROW_NW - pre-defined image on 5x5 display
		ARROW_S - pre-defined image on 5x5 display
		ARROW_SE - pre-defined image on 5x5 display
		ARROW_SW - pre-defined image on 5x5 display
		ARROW_W - pre-defined image on 5x5 display
		ASLEEP - pre-defined image on 5x5 display
		BUTTERFLY - pre-defined image on 5x5 display
		CHESSBOARD - pre-defined image on 5x5 display
		CLOCK1 - pre-defined image on 5x5 display
		CLOCK10 - pre-defined image on 5x5 display
		CLOCK11 - pre-defined image on 5x5 display
		CLOCK12 - pre-defined image on 5x5 display
		CLOCK2 - pre-defined image on 5x5 display
		CLOCK3 - pre-defined image on 5x5 display
		CLOCK4 - pre-defined image on 5x5 display
		CLOCK5 - pre-defined image on 5x5 display
		CLOCK6 - pre-defined image on 5x5 display
		CLOCK7 - pre-defined image on 5x5 display
		CLOCK8 - pre-defined image on 5x5 display
		CLOCK9 - pre-defined image on 5x5 display
		CONFUSED - pre-defined image on 5x5 display
		COW - pre-defined image on 5x5 display
		DIAMOND - pre-defined image on 5x5 display
		DIAMOND_SMALL - pre-defined image on 5x5 display
		DUCK - pre-defined image on 5x5 display
		FABULOUS - pre-defined image on 5x5 display
		GHOST - pre-defined image on 5x5 display
		GIRAFFE - pre-defined image on 5x5 display
		GO_DOWN - pre-defined image on 5x5 display
		GO_LEFT - pre-defined image on 5x5 display
		GO_RIGHT - pre-defined image on 5x5 display
		GO_UP - pre-defined image on 5x5 display
		HAPPY - pre-defined image on 5x5 display
		HEART - pre-defined image on 5x5 display
		HEART_SMALL - pre-defined image on 5x5 display
		HOUSE - pre-defined image on 5x5 display
		MEH - pre-defined image on 5x5 display
		MUSIC_CROTCHET - pre-defined image on 5x5 display
		MUSIC_QUAVER - pre-defined image on 5x5 display
		MUSIC_QUAVERS - pre-defined image on 5x5 display
		NO - pre-defined image on 5x5 display
		PACMAN - pre-defined image on 5x5 display
		PITCHFORK - pre-defined image on 5x5 display
		RABBIT - pre-defined image on 5x5 display
		ROLLERSKATE - pre-defined image on 5x5 display
		SAD - pre-defined image on 5x5 display
		SILLY - pre-defined image on 5x5 display
		SKULL - pre-defined image on 5x5 display
		SMILE - pre-defined image on 5x5 display
		SNAKE - pre-defined image on 5x5 display
		SQUARE - pre-defined image on 5x5 display
		SQUARE_SMALL - pre-defined image on 5x5 display
		STICKFIGURE - pre-defined image on 5x5 display
		SURPRISED - pre-defined image on 5x5 display
		SWORD - pre-defined image on 5x5 display
		TARGET - pre-defined image on 5x5 display
		TORTOISE - pre-defined image on 5x5 display
		TRIANGLE - pre-defined image on 5x5 display
		TRIANGLE_LEFT - pre-defined image on 5x5 display
		TSHIRT - pre-defined image on 5x5 display
		UMBRELLA - pre-defined image on 5x5 display
		XMAS - pre-defined image on 5x5 display
		YES - pre-defined image on 5x5 display
		get_pixel(Image object, int, int) - retrives the intensity of the pixel at x,y
		height(Image object) - height of image object
		set_pixel(Image object,int,int,int) - set pixel at x, y with intensity between 0 and 9
		shift_down(Image object,int) - shift down all pixels of the image obect by N rows. returns a new image object
		shift_left(Image object,int) - shift left all pixels of the image obect by N rows. returns a new image object
		shift_right(Image object,int) - shift right all pixels of the image obect by N rows. returns a new image object
		shift_up(Image object,int) - shift up all pixels of the image obect by N rows. returns a new image object
		width(Image object) - width of image object
	USB_VCP
		any - ???
		close - ???
		read - ???
		readinto - ???
		readline - ???
		send - ???
		write - ???
		__bases__ - ???
		__del__ - ???
		CTS - ???
		RTS - ???
		callback - ???
		init - ???
		isconnected - ???
		readlines - ???
		recv - ???
		setinterrupt - ???
	battery
		temperature() - shows battery temp
		voltage() - shows voltage (charge_voltage in info)
		info() - dict of:
			temperature,charge_voltage,charge_current,
			charge_voltage_filtered,error_state,
			charger_state,battery_capacity_left
		current() - current voltage pulled (charge_current in info)
		charger_detect() - if cable is plugged in (charger_state in info)
		capacity_left() - percent battery left (battery_capacity_left in info)
		BATTERY_BAD_BATTERY - returns -5
		BATTERY_HUB_TEMPERATURE_CRITICAL_OUT_OF_RANGE - returns -2
		BATTERY_NO_ERROR - returns 0
		BATTERY_TEMPERATURE_OUT_OF_RANGE - returns -2
		BATTERY_TEMPERATURE_SENSOR_FAIL - returns -3
		BATTERY_VOLTAGE_TOO_LOW - returns -5
		CHARGER_STATE_CHARGING_COMPLETED - returns 2
		CHARGER_STATE_CHARGING_ONGOING - returns 1
		CHARGER_STATE_DISCHARGING - returns 0
		CHARGER_STATE_FAIL - returns -1
		USB_CH_PORT_CDP - returns 2
		USB_CH_PORT_DCP - returns 3
		USB_CH_PORT_NONE - returns 0
		USB_CH_PORT_SDP - returns 0
	ble
		callback - callback if bluetooth is connected
		connect(int) - no idea how to connect via int
		mac() - show mac address of hub
		rssi() - power level of hub
		scan(int) - when called scanning seems to happen. no idea what the int does
		scan_result() - results of bluetooth scan
	bluetooth
		discoverable() - is hub discoverable
		info() - dict of:
			mac_addr, service_uuid, name,
			iap {
				device_version,authentication_revision,
				device_id, certificate_serial_no,
				protocol_major_version, protocol_minor_version
			}, known_devices, device_uuid
	button
		center,left,right
			callback - callback function if button triggered
			is_pressed() - shows current state
			on_change(function name) - calls the function which needs 1 argument for time (0 pressed, <time> until release)
			presses() - counts presses since last call
			was_pressed() - returns 1 if it was pressed since last call
	display
		clear() - clears the display
		callback(func ref / None) - callback function when display draws new image or clears (rotation wont trigger)
		pixel(int,int) - give pixel intensity at x,y 
		rotation(int) - rotate the display by 90,180,270,...
		show(image object) - shows the image object i.e hub.Image('00000:00900:09990:99999:00000')
	file_transfer(str, int) - ???
	info() - info about the hub:
		1ms_tick_min, 1ms_tick_on_time, product_variant, 1ms_tick_miss,
		1ms_tick_max, 1ms_tick_total, hardware_version, device_uuid
	led(int,int,int) = sets the r,g,b value of the led (white is (255, 70, 35))
	led() - returns current led color
	motion
		BACK - is str -> back
		DOUBLETAPPED - is str -> doubletapped
		DOWN - is str -> down
		FREEFALL - is str -> freefall
		FRONT - is str -> front
		LEFTSIDE - is str -> leftside
		NONE - is str -> NULL
		RIGHTSIDE - is str -> rightside
		SHAKE - is str -> shake
		TAPPED - is str -> tapped
		UP - is str -> up
		accelerometer () - int of x, y, z acceleration
		accelerometer_filter () - int of x, y, z acceleration less noisy
		callback(func ref / None) - callback function when any of the all caps state happen. sender has state
		gesture - listen for any of the all caps state
		gyroscope() - int of x, y, z gyroscope
		gyroscope_filter - int of x, y, z gyroscope less noisy
		orientation() - orientation of the hub: 'front', 'back', 'leftside', 'rigtside', 'up', 'down'
		position() - position in angle for example to calculate the orientation
		preset_yaw(int) - set yaw
		reset_yaw() - reset yaw
		was_gesture(any of the all caps state) - was the hub in such an orientation. reset after called
	port
		A - returns object -> Port(A)
		ATTACHED - returns 1 (but what is attached?!?!)
		B - returns object -> Port(B)
		C - returns object -> Port(C)
		D - returns object -> Port(D)
		DETACHED - returns 0 (but what is detached?!?!)
		E - returns object -> Port(E)
		F - returns object -> Port(F)
		MODE_DEFAULT - returns 0
		MODE_FULL_DUPLEX - returns 1
		MODE_GPIO - returns 3
		MODE_HALF_DUPLEX - returns 2
	power_off() - turns off the hub
	repl_restart() - froze the hub but by name should restart the rpl
	sound
		SOUND_SAWTOOTH - returns 3
		SOUND_SIN - returns 0
		SOUND_SQUARE - returns 1
		SOUND_TRIANGLE - returns 2
		beep(int,int) - first argument is sound in herz, second is time in ms. works async
		callback(func ref / None) - callback function when sound is played. sender is 0
		play(path) - plays any file in extra_files:
			['Affirmative', 'Damage', 'Exterminate', 'Fire', 'Grab', 'Hammer', 'Laser', 'Laugh', 'Mission Accomplished', 'Punch', 'Scanning', 'Seek and Destroy', 'Shut Down', 'Target Acquired', 'Target Destroyed', 'Whirl', '1234', 'Delivery', 'Dizzy', 'Goodbye', 'Hello', 'Hi', 'Hi 5', 'Humming', 'Chuckle', 'Like', 'No', 'Ouch', 'Sad', 'Scared', 'Tadaa', 'Wow', 'Yes', 'Yipee', 'Yuck', 'Activate', 'Kick', 'Shake', 'Deactivate', 'Initialize', 'Brick Eating', 'Horn', 'Hydraulics Down', 'Hydraulics Up', 'Reverse', 'Revving', 'Shooting', 'Play', 'Countdown', 'Countdown Tick', 'Error', 'Ping', 'Success Chime', 'Bowling', 'Celebrate', 'Explosion', 'Goal', 'Hit', 'Slam Dunk', 'Strike']
		volume(int) / () - if nothing is pased returns volume. otherwise set volume from 0 to 10 (10 max) 
	status - returns status of hub for example:
		'gyroscope': (0, -1, 0), 'position': (-30, 0, 0), 'accelerometer': (-7, -3, 991), 'port': {'C': [], 'D': [], 'B': [], 'E': [], 'A': [], 'F': []}, 'display': '09000:09900:09990:09900:09000'
	supervision
		info() - info about the hub state
		{'continous_current_too_high': False, 'peek_current_too_high': False, 'temperature_too_high': False, 'continuous_current': 110, 'temperature_way_too_high': False}
	temperature() - temperature of the environment. different measure than hub.battery.temperature

firmware
	appl_checksum() - returns 1231192444
	appl_image_initialise() - returns nothing
	appl_image_read(int) - returns a bytearray
	appl_image_store(str) - returns length of str
	bootloader_version() - returns version of bootloader
	erase_superblock - didn't dare to execute
	ext_flash_erase - didn't dare to execute
	ext_flash_read_length - didn't dare to execute
	flash_read - didn't dare to execute
	flash_write - didn't dare to execute
	info - gets firmware info
		{'appl_checksum': 1231192444, 'new_appl_image_stored_checksum': 0, 'appl_calc_checksum': 1231192444, 'new_appl_valid': False, 'new_appl_image_calc_checksum': 0, 'new_image_size': 0, 'currently_stored_bytes': 9, 'upload_finished': False, 'spi_flash_size': '32 MBytes', 'valid': 0}
util.animations
	Image - Image class see hub.Image
	hub - see hub
	shift_left - see hub.Image.shift_left
	shift_right -see hub.Image.shift_left
	utime - see micropython utime module
	get_color_percentage([int,int,int], [int,int,int]) - two rgb values 255 base maybe?!
	color_percentage([int,int,int], int) - reduce rgb color by percent 
	DIM_WHITE - returns color rgb (135, 25, 10)
	BLACK -returns color rgb (0, 0, 0)
	DISPLAY_WIDTH - returns 5
	DISPLAY_HEIGHT - returns 5
	chain_animations(list/str) - returns a generator for each element of list or str
	shift_out_to_left(Image object) - returns generator with new image object shifting the original out to the left
	shift_out_to_right(Image object) - returns generator with new image object shifting the original out to the right
	shift_out_to_top(Image object) - returns generator with new image object shifting the original out to the top
	shift_out_to_bottom(Image object) - returns generator with new image object shifting the original out to the bottom
	shift_in_from_left(Image object) - returns generator with new image object shifting the original from to the left
	shift_in_from_right(Image object) - returns generator with new image object shifting the original from to the right
	shift_in_from_top(Image object) - returns generator with new image object shifting the original in from the top
	shift_in_from_bottom(Image object) - returns generator with new image object shifting the original in from the bottom
	shift_in_from_bottom_left(Image object) - returns generator with new image object shifting the original in from the bottom left
	shift_in_from_top_right(Image object) - returns generator with new image object shifting the original in from the top right
	streaming_animation() - returns an animation sequence of image objects
	download_animation() - returns an animation sequence of image objects
	bt_animation - returns a generator containing an animation sequence of image objects
	BOOTUP_FRAMES - tuple of image objects
	bootup_animation() - plays the bootup animation
	SHUTDOWN_FRAMES -returns an animation sequence of image objects
	shutdown_animation - plays the shutdown animation
	led_fade_to([int,int,int], int) - rgb and some int returns a generator. will fade the LED for example when used in a loop with sleep:
		for b in utils.animations.led_fade_to([244,2,1],1000):
			sleep(0.2)
	led_fade_in_out - same as led_fade_to but other way around
util.color
	get_color_percentage - see util.animations.get_color_percentage
	color_percentage - see util.animations.get_color_percentage
	DIM_WHITE - (135, 25, 10)
	BLACK -(0, 0, 0)
	VIOLET - (255, 8, 23)
	BLUE - (0, 0, 80)
	AZURE - (0, 57, 57)
	GREEN - (0, 195, 0)
	YELLOW - (255, 35, 0)
	RED - (255, 0, 0)
	WHITE - (255, 70, 35)
	rgb_percentage(int,int,int,int) - rgb to which a percentage is applied to return a dimmer color
	get_rgb_percentage - not sure how to use
util.constant
	BT_VCP - see above
	Image - see above
	USB_VCP - see above
	hub - see above
	PORTS - returns a list of available ports:
		{'C': Port(C), 'B': Port(B), 'D': Port(D), 'E': Port(E), 'A': Port(A), 'F': Port(F)}
	LPF2_FLIPPER_MOTOR_SMALL - returns 65
	LPF2_FLIPPER_MOTOR_MEDIUM - returns 48
	LPF2_FLIPPER_MOTOR_LARGE - returns 49
	LPF2_FLIPPER_COLOR - returns 61
	LPF2_FLIPPER_DISTANCE - returns 62
	LPF2_FLIPPER_FORCE - returns 63
	LPF2_ACCELERATION - returns 57
	LPF2_GYRO - returns 58
	LPF2_ORIENTATION - returns 59
	LPF2_STONE_GREY_MOTOR_MEDIUM - returns 75
	LPF2_STONE_GREY_MOTOR_LARGE - returns 76
	MOTOR_TYPES - returns (65, 48, 49, 75, 76)
	NO_STATUS - returns -1
	SUCCESS - returns 0
	INTERRUPTED - returns 1
	STALLED - returns 2
	FLOAT - returns 0
	BRAKE - returns 1
	HOLD - returns 2
	NO_KEY - returns -1
	NUMBER - returns 0
	STRING - returns 1
	BOOLEAN - returns 2
	VAR_DEFAULTS - returns {0: 0, 1: '', 2: False}
	LONG_PRESS_MS - returns 3000
	INACTIVE_SHUTDOWN_MS - returns 300000
	INACTIVE_SHUTDOWN_BT_MS - returns 1200000
	TIMER_PACE_HIGH - returns 16
	TIMER_PACE_LOW - 48
	Sounds
		NAVIGATION - returns 'sounds/menu_click'
		NAVIGATION_FAST - returns 'sounds/menu_fastback'
		PROGRAM_START - returns 'sounds/menu_program_start'
		PROGRAM_STOP - returns 'sounds/menu_program_stop'
		STARTUP - returns 'sounds/startup'
		SHUTDOWN - returns 'sounds/menu_shutdown'
	DEFAULT_IMAGE - returns (Image('09090:99999:99999:09990:00900:'), Image('09000:09900:09990:09900:09000:'))
	SLOTS_IMAGE - returns long series of image objects
	LOCAL_NAME - returns '/local_name.txt'
	DATA_DIR - returns '/data'
	LINEGRAPH_DIR - returns '/data/linegraph'
util.error_handler 
	b2a_base64(str) - base64 encoder
	hub - see above
	sys - micropython
	uio - micropython
	ure - micropython
	version - see version.py
	BLACK - returns (0, 0, 0)
	RED - return (255, 0, 0)
	error_handler - 'ErrorHandler' object
	notifications - see protocol/notifications.mpy
	log_critical_error(int/str) - writes to logfile
	get_event_loop() - get the current eventloop returns EventLoop object
	PROGRAM_EXECUTION_ERROR - returns 0
	PROGRAM_EXECUTION_MEMORY_ERROR - returns 1
	ErrorHandler - returns ErrorHandler object

@4doom4
Copy link

4doom4 commented Jan 3, 2021 •
edited
Loading

a little more:

util.log
	gc - micropython
	sys - micropython
	uio - micropython
	uos - micropython
	utime - micropython
	log_critical_error(int/str) - writes to logfile (all the rest deleted)
	log_to_file - defines log file
	_LOG_FILE - default logiles -> './runtime.log'
	cat_log() - returns content of logfile
	clear_log() - deletes logfile
	_write_to_log(str) - write to log file (all the rest deleted)
	timed_fn_buffer - returns an empty list
	timed_function - takes a function for something?!?!
util.motor
	dir_to_speed(int,int) - ???
	clamp_speed(int) - ???
	clamp_power(int) - ???
util.print_override
	BT_VCP - see above
	USB_VCP - see above
	b2a_base64 - see above
	ticks_diff(int,int) - difference between the two ints
	ticks_ms - ticks for time measurement
	uio - micrpythin
	JSONRPC - JSON-RPC class
		emit - ???
		stream - ???
		add_method - ???
		resume_suspended_msg - ???
		parse_chunk - ???
		methods - ???
		pending - ???
		parse_buffer - ???
		reply - ???
		error - ???
		_handle_message - ???
		suspend_current_message - ???
		_pop_suspend_message - ???
		clear_methods - ???
		emit_large - ???
		call - ???
		cancel_call - ???
	_NOT_CONNECTED_ERROR - returns 'The programming app is not connected to the hub.'
	spikeprint(str) - print to mindstorms / spike console
util.resetter
	hub - see above
	schedule(func, arg) - calls a function with an argument but not async. same as micropython.schedule
	sleep_ms(int) - sleep function
	ticks_diff(int,int) - difference between the two ints
	ticks_ms() - ticks for time measurement
	_STARTED_AT - ticks in ms when started
	wait_until_ready_after_restart() - ???
	RTTimer - class
		start - ???
		repl_reset - ???
		__repl_reset - ???
util.rotation
	hub - see above
	_CURRENT_ROTATION - returns 0
	dir_to_rotation(int) - returns 90????
	rotate_hub_display(int) - rotate display by angle of 90, 180
	rotate_hub_display_to_value - i tried many int values but nothing works
	rotate_hub_display_to_orientation(int) - takes 3, 93, 183, etc. ?!?!
util.schedule
	micropython - micropython
	mp_schedule(func, arg) - calls a function with an argument but not async. same as micropython.schedule
util.scratch
	compare(float,float) - difference
	math - micropython
	tan(float) - tan of float
	ure - micropython
	color - util/color.py
	NO_KEY - returns -1
	NUMBER - returns 0
	BOOLEAN - returns 2
	VAR_DEFAULTS - returns {0: 0, 1: '', 2: False}
	orientation_to_number(int/str) - probably some string. i tried many int
	to_number(str) - conv str to float
	to_boolean(arg) - convert arg to bool i.e.'false','0' -> False or 'True', 'true', '1', 'hello' -> True
	is_int(arg) - returns true if arg int
	convert_brightness(int) - converts increments of ten back to brightness 10 -> 1, 40 -> 4, 50 -> 4, 100 -> 9
	adjust_brightness(int,int) - does something with two increments of 10 and returns brightness
	partition_image_str(str) - brings string in image format of five char + :
	convert_image(str) - convert str to image string
	convert_animation_frame(list of int) - converts list to image str
	clamp(int) - clamps int to max 100 (if int > 100 return 100)
	wrap_clamp - wraps the clamp value around to restart at 0
	color_to_number(str) - returns a number for different colors like 'green' -> 5
	number_to_color(int) - returns color name for number like 5 -> 'green' 
	number_color_to_rgb - returns the rgb for a number like 5 -> (0, 195, 0) (which is green)
	ORIENTATIONS - possible orientations: ('', 'front', 'back', 'up', 'down', 'rightside', 'leftside')
	number_to_orientation(int) - returns the str based on the position in ORIENTATIONS
	sanitize_ports(str) - returns a port letter which is ensured to be available
	PAIR_REGEX - returns a regex object
	sanitize_movement_ports(str) - does something to the str to make sure the movement port is returned but what is a movement port?
	percent_to_int(int,int) - first is the percent and the second is the number of which you want the percent
	percent_to_frequency(int,int,int,int) - ???
	note_to_frequency(int) - returns the frequence for some notes which are in int.
		60 - C - 261hz
		61 - C# - 277hz
		62 - D - 293hz
		etc.
	get_variable - gets attribute vars from some class which supports it
	pitch_to_freq(int,int,int,int)- convers the pitch to frequency
util.sensors
	hub - see above
	LPF2_FLIPPER_MOTOR_SMALL - see above
	LPF2_FLIPPER_MOTOR_MEDIUM - see above
	LPF2_FLIPPER_MOTOR_LARGE - see above
	LPF2_FLIPPER_COLOR - see above
	LPF2_FLIPPER_DISTANCE - see above
	LPF2_FLIPPER_FORCE - see above
	LPF2_STONE_GREY_MOTOR_MEDIUM - see above
	LPF2_STONE_GREY_MOTOR_LARGE - see above
	update_sensor_data() - forces update
	update_battery_status() - forces battery status update
	orientation_to_number(str) - takes the orientation string from util.scratch.ORIENTATIONS and returns the index
	get_time - time since util.time.start_time()
	_DEFAULT_MODE - returns
		{48: [(1, 0), (2, 2), (3, 1), (0, 0)], 65: [(1, 0), (2, 2), (3, 1), (1, 0)], 49: [(1, 0), (2, 2), (3, 1), (0, 0)], 75: [(1, 0), (2, 2), (3, 1), (0, 0)], 76: [(1, 0), (2, 2), (3, 1), (0, 0)], 61: [(1, 0), (0, 0), (5, 0), (5, 1), (5, 2)], 62: [(0, 0)], 63: [(0, 0), (1, 0), (4, 0)]}
	_REVERSE_MODES - returns
		{48: [3, 0, 1, 2], 65: [3, 0, 1, 2], 49: [3, 0, 1, 2], 75: [3, 0, 1, 2], 76: [3, 0, 1, 2], 61: [1, 0, 2, 3, 4], 62: [0], 63: [0, 1, -1, -1, 2]}
	_PORTS - returns
		[Port(A), Port(B), Port(C), Port(D), Port(E), Port(F)]
	_PORT_TYPE - returns
		[0, 0, 0, 0, 0, 0]
	_EVENT_MODE - returns
		[[], [], [], [], [], []]
	register_ports - ???
	_SYNC_DISPLAY - returns False
	_NO_DATA - returns ()
	sensor_data - returns information about the hub gyro and ports i.e. [[0, ()], [0, ()], [0, ()], [0, ()], [0, ()], [0, ()], (-15, 8, 996), (0, -1, 0), (10, 0, 0), '', 0]
	_MOTOR_TYPES - returns [65, 48, 49, 75, 76]
	_is_motor(str) - probably uses port object to see if a motor is attached?!
	_PORT_INDEX_MAP - returns ['A', 'B', 'C', 'D', 'E', 'F', 'ACCELEROMETER', 'GYROSCOPE', 'POSITION', 'ORIENTATION', 'TIMER']
	get_sensor_value - ???
	is_type(int) - ???
	battery_status - returns [8.147, 100, False]
	_type_change_handler - ???
	reset_to_default_mode - ???
	set_display_sync - ???
	current_motion - ???
util.storage
	EEXIST - returns 17
	ENOENT - returns 2
	uos - micropython
	urandom - micropython
	ure - micropython
	LOCAL_NAME - returns '/local_name.txt'
	get_storage_information() - returns a dict of folders and files, theire size, modification, etc.
	read_local_name - returns 'LEGO Hub'
	__STORAGE_PATH__ - returns './projects'
	__META_PATH__ - returns './projects/.slots'
	__PROGRAM_PATH__ - returns './projects/{0}'
	__PROGRAM_PATH_EXT__ - returns './projects/{0}.py'
	__FORCE_RESET_PATH__ - returns './reset
	PROGRAM_TYPE_PYTHON - returns 'python'
	PROGRAM_TYPE_SCRATCH - returns 'scratch'
	open_program(file) - opens a file using the io module
	close_program(file) - closes a file 
	get_program_project_id(int) - project id from number of program
	get_program_type(int) - project type from number of program
	get_path(int) - project path to file from number of program
	clear_slot - didnt try it
	generate_project_id() - generates an id for a compatible project
	get_used_slots() - show all the used slots in the programmer
	read_program(int) - reads code from a program in a slot
	_BT_PREFIX - returns 'LEGO Hub@'
	write_local_name(str) - not sure
	move_slot - didnt try it
	_move_slot_lookup - didnt try it
	_ensure_folder_exists() - ???
	_get_metadata() - gets the project/.slot data
	_set_metadata() - didnt try it put probably sets the project/.slot data
	set_force_reset - didnt try it
	pop_force_reset - didnt try it
	_file_to_slotid - probably moves a python file from disk to a slot in the hub
util.time
	ticks_diff - see above
	ticks_ms - see above 
	get_time - time since util.time.start_time()
	_STARTED_AT - when was the timer started
	_RUNNING - is the timer running
	_STOPPED_AT - when was it stopped
	reset_time() - reset the timer
	start_time() - start the timer
	stop_time() - stop the timer

@pitust
Copy link
Contributor

pitust commented Jan 3, 2021

All the internals (firmware and hub), with my analysis on there:

hub
	BT_VCP() - class, the bluetooth connection to whatever is paired
		any - are there bytes available?
		close - no-op
		read - no-op?
		readinto - takes a byte array, and fills it with available data
		readline - ???
		send - write to the bluetooth connection
		write - write to the bluetooth connection
		callback - ???
		isconnected - tells you whether the bluetooth is connected
		readlines - ???
		recv - fill up the given bytearray
		setinterrupt - sets the interrupt key, aka the key to press to cause a `KeyboardInterrupt`. Defaults to `0x03` (control-C)
	Image(image str) / () - returns Image object of image str i.e. '00090:09020:' or empty image object
		ALL_ARROWS - pre-defined image on 5x5 display
		ALL_CLOCKS - pre-defined image on 5x5 display
		ANGRY - pre-defined image on 5x5 display
		ARROW_E - pre-defined image on 5x5 display
		ARROW_N - pre-defined image on 5x5 display
		ARROW_NE - pre-defined image on 5x5 display
		ARROW_NW - pre-defined image on 5x5 display
		ARROW_S - pre-defined image on 5x5 display
		ARROW_SE - pre-defined image on 5x5 display
		ARROW_SW - pre-defined image on 5x5 display
		ARROW_W - pre-defined image on 5x5 display
		ASLEEP - pre-defined image on 5x5 display
		BUTTERFLY - pre-defined image on 5x5 display
		CHESSBOARD - pre-defined image on 5x5 display
		CLOCK1 - pre-defined image on 5x5 display
		CLOCK10 - pre-defined image on 5x5 display
		CLOCK11 - pre-defined image on 5x5 display
		CLOCK12 - pre-defined image on 5x5 display
		CLOCK2 - pre-defined image on 5x5 display
		CLOCK3 - pre-defined image on 5x5 display
		CLOCK4 - pre-defined image on 5x5 display
		CLOCK5 - pre-defined image on 5x5 display
		CLOCK6 - pre-defined image on 5x5 display
		CLOCK7 - pre-defined image on 5x5 display
		CLOCK8 - pre-defined image on 5x5 display
		CLOCK9 - pre-defined image on 5x5 display
		CONFUSED - pre-defined image on 5x5 display
		COW - pre-defined image on 5x5 display
		DIAMOND - pre-defined image on 5x5 display
		DIAMOND_SMALL - pre-defined image on 5x5 display
		DUCK - pre-defined image on 5x5 display
		FABULOUS - pre-defined image on 5x5 display
		GHOST - pre-defined image on 5x5 display
		GIRAFFE - pre-defined image on 5x5 display
		GO_DOWN - pre-defined image on 5x5 display
		GO_LEFT - pre-defined image on 5x5 display
		GO_RIGHT - pre-defined image on 5x5 display
		GO_UP - pre-defined image on 5x5 display
		HAPPY - pre-defined image on 5x5 display
		HEART - pre-defined image on 5x5 display
		HEART_SMALL - pre-defined image on 5x5 display
		HOUSE - pre-defined image on 5x5 display
		MEH - pre-defined image on 5x5 display
		MUSIC_CROTCHET - pre-defined image on 5x5 display
		MUSIC_QUAVER - pre-defined image on 5x5 display
		MUSIC_QUAVERS - pre-defined image on 5x5 display
		NO - pre-defined image on 5x5 display
		PACMAN - pre-defined image on 5x5 display
		PITCHFORK - pre-defined image on 5x5 display
		RABBIT - pre-defined image on 5x5 display
		ROLLERSKATE - pre-defined image on 5x5 display
		SAD - pre-defined image on 5x5 display
		SILLY - pre-defined image on 5x5 display
		SKULL - pre-defined image on 5x5 display
		SMILE - pre-defined image on 5x5 display
		SNAKE - pre-defined image on 5x5 display
		SQUARE - pre-defined image on 5x5 display
		SQUARE_SMALL - pre-defined image on 5x5 display
		STICKFIGURE - pre-defined image on 5x5 display
		SURPRISED - pre-defined image on 5x5 display
		SWORD - pre-defined image on 5x5 display
		TARGET - pre-defined image on 5x5 display
		TORTOISE - pre-defined image on 5x5 display
		TRIANGLE - pre-defined image on 5x5 display
		TRIANGLE_LEFT - pre-defined image on 5x5 display
		TSHIRT - pre-defined image on 5x5 display
		UMBRELLA - pre-defined image on 5x5 display
		XMAS - pre-defined image on 5x5 display
		YES - pre-defined image on 5x5 display
		get_pixel(Image object, int, int) - retrives the intensity of the pixel at x,y
		height(Image object) - height of image object
		set_pixel(Image object,int,int,int) - set pixel at x, y with intensity between 0 and 9
		shift_down(Image object,int) - shift down all pixels of the image obect by N rows. returns a new image object
		shift_left(Image object,int) - shift left all pixels of the image obect by N rows. returns a new image object
		shift_right(Image object,int) - shift right all pixels of the image obect by N rows. returns a new image object
		shift_up(Image object,int) - shift up all pixels of the image obect by N rows. returns a new image object
		width(Image object) - width of image object
	USB_VCP - same as BT_VCP but for USB
	battery
		temperature() - shows battery temp
		voltage() - shows voltage (charge_voltage in info)
		info() - dict of:
			temperature,charge_voltage,charge_current,
			charge_voltage_filtered,error_state,
			charger_state,battery_capacity_left
		current() - current voltage pulled (charge_current in info)
		charger_detect() - if cable is plugged in (charger_state in info)
		capacity_left() - percent battery left (battery_capacity_left in info)
		BATTERY_BAD_BATTERY - returns -5
		BATTERY_HUB_TEMPERATURE_CRITICAL_OUT_OF_RANGE - returns -2
		BATTERY_NO_ERROR - returns 0
		BATTERY_TEMPERATURE_OUT_OF_RANGE - returns -2
		BATTERY_TEMPERATURE_SENSOR_FAIL - returns -3
		BATTERY_VOLTAGE_TOO_LOW - returns -5
		CHARGER_STATE_CHARGING_COMPLETED - returns 2
		CHARGER_STATE_CHARGING_ONGOING - returns 1
		CHARGER_STATE_DISCHARGING - returns 0
		CHARGER_STATE_FAIL - returns -1
		USB_CH_PORT_CDP - returns 2
		USB_CH_PORT_DCP - returns 3
		USB_CH_PORT_NONE - returns 0
		USB_CH_PORT_SDP - returns 0
	ble
		callback - callback if bluetooth is connected
		connect(int) - no idea how to connect via int
		mac() - show mac address of hub
		rssi() - power level of hub
		scan(int) - when called scanning seems to happen. no idea what the int does
		scan_result() - results of bluetooth scan
	bluetooth
		discoverable() - is hub discoverable
		info() - dict of:
			mac_addr, service_uuid, name,
			iap {
				device_version,authentication_revision,
				device_id, certificate_serial_no,
				protocol_major_version, protocol_minor_version
			}, known_devices, device_uuid
	button
		center,left,right
			callback - callback function if button triggered
			is_pressed() - shows current state
			on_change(function name) - calls the function which needs 1 argument for time (0 pressed, <time> until release)
			presses() - counts presses since last call
			was_pressed() - returns 1 if it was pressed since last call
	display
		clear() - clears the display
		callback(func ref / None) - callback function when display draws new image or clears (rotation wont trigger)
		pixel(int,int) - give pixel intensity at x,y 
		rotation(int) - rotate the display by 90,180,270,...
		show(image object) - shows the image object i.e hub.Image('00000:00900:09990:99999:00000')
	file_transfer(str, int) - used for file transfers from the app to the hub
	info() - info about the hub:
		1ms_tick_min, 1ms_tick_on_time, product_variant, 1ms_tick_miss,
		1ms_tick_max, 1ms_tick_total, hardware_version, device_uuid
	led(int,int,int) = sets the r,g,b value of the led (white is (255, 70, 35))
	led() - returns current led color
	motion
		BACK - is str -> back
		DOUBLETAPPED - is str -> doubletapped
		DOWN - is str -> down
		FREEFALL - is str -> freefall
		FRONT - is str -> front
		LEFTSIDE - is str -> leftside
		NONE - is str -> NULL
		RIGHTSIDE - is str -> rightside
		SHAKE - is str -> shake
		TAPPED - is str -> tapped
		UP - is str -> up
		accelerometer () - int of x, y, z acceleration
		accelerometer_filter () - int of x, y, z acceleration less noisy
		callback(func ref / None) - callback function when any of the all caps state happen. sender has state
		gesture - listen for any of the all caps state
		gyroscope() - int of x, y, z gyroscope
		gyroscope_filter - int of x, y, z gyroscope less noisy
		orientation() - orientation of the hub: 'front', 'back', 'leftside', 'rigtside', 'up', 'down'
		position() - position in angle for example to calculate the orientation
		preset_yaw(int) - set yaw
		reset_yaw() - reset yaw
		was_gesture(any of the all caps state) - was the hub in such an orientation. reset after called
	port
		A - returns object -> Port(A)
		ATTACHED - returns 1 (but what is attached?!?!)
		B - returns object -> Port(B)
		C - returns object -> Port(C)
		D - returns object -> Port(D)
		DETACHED - returns 0 (but what is detached?!?!)
		E - returns object -> Port(E)
		F - returns object -> Port(F)
		MODE_DEFAULT - returns 0
		MODE_FULL_DUPLEX - returns 1
		MODE_GPIO - returns 3
		MODE_HALF_DUPLEX - returns 2
	power_off() - turns off the hub, **works async** (you propably should while true after this)
	repl_restart() - pass a "machine word" to make this restart a repl (any small int works)
	sound
		SOUND_SAWTOOTH - returns 3
		SOUND_SIN - returns 0
		SOUND_SQUARE - returns 1
		SOUND_TRIANGLE - returns 2
		beep(int,int) - first argument is sound in herz, second is time in ms. works async
		callback(func ref / None) - callback function when sound is played. sender is 0
		play(path) - plays any file in extra_files:
			['Affirmative', 'Damage', 'Exterminate', 'Fire', 'Grab', 'Hammer', 'Laser', 'Laugh', 'Mission Accomplished', 'Punch', 'Scanning', 'Seek and Destroy', 'Shut Down', 'Target Acquired', 'Target Destroyed', 'Whirl', '1234', 'Delivery', 'Dizzy', 'Goodbye', 'Hello', 'Hi', 'Hi 5', 'Humming', 'Chuckle', 'Like', 'No', 'Ouch', 'Sad', 'Scared', 'Tadaa', 'Wow', 'Yes', 'Yipee', 'Yuck', 'Activate', 'Kick', 'Shake', 'Deactivate', 'Initialize', 'Brick Eating', 'Horn', 'Hydraulics Down', 'Hydraulics Up', 'Reverse', 'Revving', 'Shooting', 'Play', 'Countdown', 'Countdown Tick', 'Error', 'Ping', 'Success Chime', 'Bowling', 'Celebrate', 'Explosion', 'Goal', 'Hit', 'Slam Dunk', 'Strike']
		volume(int) / () - if nothing is pased returns volume. otherwise set volume from 0 to 10 (10 max) 
	status - returns status of hub for example:
		'gyroscope': (0, -1, 0), 'position': (-30, 0, 0), 'accelerometer': (-7, -3, 991), 'port': {'C': [], 'D': [], 'B': [], 'E': [], 'A': [], 'F': []}, 'display': '09000:09900:09990:09900:09000'
	supervision
		info() - info about the hub state
		{'continous_current_too_high': False, 'peek_current_too_high': False, 'temperature_too_high': False, 'continuous_current': 110, 'temperature_way_too_high': False}
	temperature() - temperature of the environment. different measure than hub.battery.temperature

firmware
	appl_checksum() - returns a checksum of the current firmware
	appl_image_initialise() - returns nothing
	appl_image_read(int) - returns a bytearray
	appl_image_store(str) - returns length of str
	bootloader_version() - returns version of bootloader
	erase_superblock - erases the littlefs superblock, effectivly removing all files (note that it really isn't "secure" erase since the data is still there and can be read from the SPI flash)
	ext_flash_erase - takes a while, seems to erase the flash and not just the superblock
	ext_flash_read_length - didn't dare to execute
	flash_read - read the internal flash
	flash_write - write the internal flash, can brick your device and the only way to unbrick it is to attach an ST-Link bridge to the hard-to-access motherboard! (maybe, but they propably fused against it)
	info - gets firmware info
		{'appl_checksum': 1231192444, 'new_appl_image_stored_checksum': 0, 'appl_calc_checksum': 1231192444, 'new_appl_valid': False, 'new_appl_image_calc_checksum': 0, 'new_image_size': 0, 'currently_stored_bytes': 9, 'upload_finished': False, 'spi_flash_size': '32 MBytes', 'valid': 0}

VCP stands for Virtual Com Port

@dlech
Copy link

dlech commented May 28, 2021

LEGO has released some documentation: https://lego.github.io/MINDSTORMS-Robot-Inventor-hub-API/index.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@gpdaniels gpdaniels

Labels
enhancement New feature or request project - simulator For issues about the hub simulator
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@dlech @gpdaniels @4doom4 @pitust