Jump to content




NAVIGATOR - Inertial Navigation for Turtles

turtle api

1 reply to this topic

#1 Purple

  • Members
  • 115 posts
  • LocationAlone in the dark, looking at the pretty lights with dreams of things I can not have.

Posted 19 March 2019 - 08:46 PM

Have you ever wished your turtles knew where they are in the world? Have you looked in vain for an API to do so only to end up staring down the ugly face of hyper complex and frankly overkill world of wireless GPS systems? Don't you just wish that there was something simple, easy and trivial to implement and use?


Well I did. And now I share my vision with you.

Navigator
Inertial navigation API for turtles.



Technical Description:
Navigator is a file backed storage based inertial navigation system for computercraft turtles. Inertial navigation is the process of calculating your current location in the world by recording your start position and than adding up your subsequent movement onto it. As such, Navigator is completely independent of any external input. It does not require rednet connections, other computers or anything else beyond the turtle and the API it uses.
The file backed storage aspect of it refers to the fact that Navigator stores its current position in a text file after each modification. This allows the program to remember and continue its work without resetting when the chunk or world is unloaded. You can save your game, exit and come back a week later and the turtle will remember where it left off as if you newer left.

This combination of functions makes Navigator ideal for automating repetitive jobs such as warehouses, delivery systems and item sorting. But it also opens up a whole world of operations outside of the range of player contact or infrastructure.

Quickstart Guide:
Navigator replaces the standard turtle movement and rotation functions with its own wrappers. Using it is as simple as importing the Navigator API and substituting all calls to turtle.left/right/forward/back/up and down with the equivalent Navigator functions.

To begin with your program you need to initialize Navigator first. This is done by calling NAVIGATOR.InitializeNavigator(). This function loads the current position data of your turtle from the file and should thus be called first in any Navigator program. The suggested code block for this function is as follows:
-- Initialize Navigator
if (NAVIGATOR.InitializeNavigator()) then
   print("Navigator file found, reading position.")
else
   print("Program running first time. Setting initial position.")
   NAVIGATOR.SetPosition(x, y, z, direction)
end

Following this the process really is as simple as replacing turtle.something function with their navigator equivalent. E.g:
Navigator.Forward()

Detailed Documentation:
function InitializeNavigator()
Initializes the navigator program by reading the stored location and facing data from the LOCATION file located next to the main program.

function SetPosition(X, Y, Z, FACING)
Sets the position and facing of the turtle.
Parameters:
X, Y and Z - Coordinates of the turtle in the game world where you've placed it.
Direction - The direction the turtle is facing initially. Direction uses the minecraft standard direction axis as per F3.

function PrintDirections()
Prints the numerical values of the 4 cardinal directions for easy reference by developers.

function GetDirectionINT(direction)
Converts the string names of the cardinal directions (e.g. "North", "E", "S", "South"...) into numbers for ease of use by developers.
Parameters:
direction - Non case sensitive string representation of the direction either as a full name (e.g. "North, "SOUTH", "eAsT") or just the first character (e.g. "N", "s", "E", "w").
Example of use:
NAVIGATOR.TurnRight(NAVIGATOR.GetDirectionINT("west"))

function GetPosition()
Retrieves the position and facing of the turtle from Navigator.
Example of use:
x, y, z, direction = NAVIGATOR.GetPosition()

function TurnLeft( goal )
Attempts to turn the turtle left.
Parameters:
Goal - (optional) The final direction the turtle should face once turning is complete. Failing to provide this parameter makes the turtle do only a single turn as per turtle.left().
Example of use:
NAVIGATOR.TurnLeft(NAVIGATOR.GetDirectionINT("west"))
NAVIGATOR.TurnLeft()

function TurnRight( goal )
Attempts to turn the turtle right.
Parameters:
Goal - (optional) The final direction the turtle should face once turning is complete. Failing to provide this parameter makes the turtle do only a single turn as per turtle.right().
Example of use:
NAVIGATOR.TurnRight(NAVIGATOR.GetDirectionINT("west"))
NAVIGATOR.TurnRight()

function Up(goal)
Attempts to move the turtle upwards.
Parameters:
Goal - (optional)The number of steps to take.

Failing to provide this parameter makes the turtle do only a single step as per turtle.up().

If the parameter is provided and the turtle fails to make all the required steps the turtle will reset to its starting position.

Example of use:
NAVIGATOR.Up(3)
Return:
boolean whether the turtle succeeded in moving upwards.

function Down(goal)
Attempts to move the turtle downward.
Parameters:
Goal - (optional)The number of steps to take.

Failing to provide this parameter makes the turtle do only a single step as per turtle.down().

If the parameter is provided and the turtle fails to make all the required steps the turtle will reset to its starting position.

Example of use:
NAVIGATOR.Down(13)
Return:
boolean whether the turtle succeeded in moving downwards.

function Forward(goal)
Attempts to move the turtle forward.
Parameters:
Goal - (optional)The number of steps to take.

Failing to provide this parameter makes the turtle do only a single step as per turtle.forward().

If the parameter is provided and the turtle fails to make all the required steps the turtle will reset to its starting position.

Example of use:
NAVIGATOR.Forward()
Return:
boolean whether the turtle succeeded in moving forward.

function Back(goal)
Attempts to move the turtle backward.
Parameters:
Goal - (optional)The number of steps to take.

Failing to provide this parameter makes the turtle do only a single step as per turtle.back().

If the parameter is provided and the turtle fails to make all the required steps the turtle will reset to its starting position.

Example of use:
NAVIGATOR.Back(47)
Return:
boolean whether the turtle succeeded in moving backward.

Example Program:
This program services 3 stacks of furnaces in my current house. Each stack is 3 tall and they are spaced 3 tiles apart. The turtle goes through them stack by stack and drops anything it finds inside into a common chest.
Spoiler


License and terms of use:
Things you can do:
- Use, modify and distribute the program in any way you see fit as long as you don't make money off it and you give me credit.
Things you can't do:
- Claim my code as your own.
- Make money off my code in any way, shape or form (donations included).


Please comment, rate and subscribe. :)
And make sure to tell me about the cool and inventive things you do with this.

Edited by Purple, 20 March 2019 - 10:14 PM.


#2 Purple

  • Members
  • 115 posts
  • LocationAlone in the dark, looking at the pretty lights with dreams of things I can not have.

Posted 20 March 2019 - 10:16 PM

UPDATE: Apparently attachments don't work for some reason. And I just figured that out now. I just did not think attaching the file would not actually attach a file. Go figure.
Anyway, here is the full code for you to save as NAVIGATOR. Sorry for the inconvenience.

Just copy paste this into a file using notepad or something.
Spoiler

Edited by Purple, 20 March 2019 - 10:22 PM.






1 user(s) are reading this topic

0 members, 1 guests, 0 anonymous users