Aware API v1.0

Please read all instructions and install required files before installing and asking questions. Suggestions and constructive criticism are always appreciated.


aware 2.0
Aware is an API that I've developed to handle turtle advanced turtle movement tracking.
[media]http://youtu.be/zN5zIhbHE-4[/media]

Spoiler

Public functions:

• moveforward()
• moveback()
• moveup()
• movedown()
• turnright()
• turnleft()
• turnto(direction)
• digmoveforward()
• digmoveup()
• digmovedown()
• movetoz(coordinate)
• movetox(coordinate)
• movetoy(coordinate)
• moveto(x, y, z, orientation)
• goto({x, y, z, orientation})
• emptyslots()
• dump()
• pushpos(id, class, {x, y, z, orientation}) <biolisten dev purposes>
• getaxis(1-4)
• getposition("name")
• setposition("name", {x, y, z, o})

Notes:

• goto and moveto do not require z axis and orientation if you only wish to travel to a relative x/y coordinate

Installation:

• copy the required files into the turtle, there are probably threads in these forums to describe how this is done.

Requirements:
utils 2.0
Download:
aware 2.0

biodesign 2.0
biodesign is a program that runs on a terminal that allows you to design, save, and later modify anything you can imagine that will fit in a 33x12 space using up to 9 block types. These designs can then be built using a compatible version of biobuild.
[media]http://youtu.be/mVZQw7g2xP0[/media]

Spoiler

usage:
biodesign "designname"

Controls

• up arrow key - move cursor up
• down arrow key - move cursor down
• left arrow key - move cursor left
• right arrow key - move cursor right
• a - move up a layer
• z - move down a layer
• c - copy current layer
• p - paste copied layer
• q - quit

Notes:

• It is possible to write a design directly to a disk using the command "biodesign disk" but that design must always be used on the disk, the files on it are not useful without it.

Requirements:
utils 2.0
matrix 2.0
Download:
biodesign 2.0

biobuild 2.0
biobuild automatically builds something designed with biodesign using aware and blocks from inventory.
[media]http://youtu.be/1W-uMaIy6VE[/media]

Spoiler

usage:
biobuild "design folder"
Notes:

• this will always build in relation to its current coordinate position in space, not necessarily the direction it is facing. You will likely notice this if using a calibrated turtle.

Requirements:
aware
utils
matrix
Download:
biobuild 2.0

biomine 2.0
biomine is a program that makes use of the aware api to mine in a (I think) very effective way.

Spoiler

coming soon to a pastebin near you

biolisten 2.0
biolisten is a fun little project I made that works with turtles and rednet to display the turtle's current position on a terminal screen or monitor.

Spoiler

coming soon to a pastebin near you

utils 2.0
utils contains some common functions used in my other programs

Spoiler

Functions:

• termwrite("text")
• copytable(table)
• download("source", "destination") – BETA
• vartofile(variable, "filename")
• varfromfile("filename")

Download:
utils 2.0

matrix 2.0
matrix is my solution to annoyance with computercraft nested tables and is used to create and modify 2 dimensional matricies.

Spoiler

Functions:

• create()
• set(array, x, y, value)
• get(array, x, y, value)
• remove(array, x y)
• size(array)

Download:
matrix 2.0

Misc:
goto
calibrate

Question: Does Aware support GPS? Having a turtle find its location from GPS, at least for the startup, would be a nice inclusion here, I think.

OmegaVest, on 27 April 2012 - 09:52 PM said:

Question: Does Aware support GPS? Having a turtle find its location from GPS, at least for the startup, would be a nice inclusion here, I think.

Right you are! That was on my list of things to do this morning that I completely forgot about! I haven't actually played with the GPS as the range seemed extremely limited but those were my thoughts exactly. Having a gps system in my house/base would allow much faster setup. I'll get on that.

I don't have the gps API enabled on this computer, but i've made a change that should attempt to use gps to locate. Let me know if it works and i'll update.
Does the gps.locate() command come back with decimals? If so I will likely have to round off the numbers to keep it from breaking

http://adf.ly/7tMHg

EDIT: the version posted here 1.1 included gps - but it likely won't work.
GPS is back out for later versions as it will not - at least not without movement - determine orientation.

Looks pretty decent, I'm downloading and I'll have to see about playing with it some.

Robd, on 27 April 2012 - 11:06 PM said:

Looks pretty decent, I'm downloading and I'll have to see about playing with it some.

any feedback would be appreciated

Well, i guess almost every real coder has already done this in a similar way (including myself) :)/>/>

I don't really play MP. I just mess around in SP. However it looks quite solid, but i would hook all native move functions so you can still use the "go" program and others. You can use rawset to overwrite the functions with your own, but don't forget to backup the native ones :)/>/>

Also i just like to add that most game engines have this axis setup (at least all pure 3D engines). It's derived from the usual view direction which is along the ground. An unaltered transformation matrix (identity) will make you look along the z-axis since x and y belong to the screen coordinates. Depending on the mathematical system used (left or right handed) the z axis might be inverted. OpenGL uses usually the mathematically correct right-handed system, while DirectX usually uses a left-handed system, but both consider y as up and x as right.

Bunny83, on 29 April 2012 - 02:58 AM said:

Well, i guess almost every real coder has already done this in a similar way (including myself) :)/>/>

I figured as much - I was just looking for ideas on how I could improve and expand it.

Bunny83, on 29 April 2012 - 02:58 AM said:

I don't really play MP. I just mess around in SP. However it looks quite solid, but i would hook all native move functions so you can still use the "go" program and others. You can use rawset to overwrite the functions with your own, but don't forget to backup the native ones :)/>/>

Cool! I had no idea you could do that. Lua seems rather closed-minded when it comes to function overloading so I hadn't really considered the possibility. That would make daughter applications much less annoying to write.

Bunny83, on 29 April 2012 - 02:58 AM said:

Also i just like to add that most game engines have this axis setup (at least all pure 3D engines). It's derived from the usual view direction which is along the ground. An unaltered transformation matrix (identity) will make you look along the z-axis since x and y belong to the screen coordinates. Depending on the mathematical system used (left or right handed) the z axis might be inverted. OpenGL uses usually the mathematically correct right-handed system, while DirectX usually uses a left-handed system, but both consider y as up and x as right.

Interesting! The only background I have in this sort of coding is in army simulations which are decidedly not 3D. My approach in mapping turtle coordinates was purely from a top-down perspective, where f=2 is north, f=0 is south, so x increases to the east, and y increases to the south the same way screen coordinates often do. Then Z as depth is sort of an abstract 'state' rather than position. That made it really easy to write my listener app because it just takes into account screen size to create a scale multiplier and then applies that to x and y with relation to their min/max reported state to display my turtle on a screen that can 'infinitely' scale to display turtle movement in relation to its home point, mining point and dropoff point. Unfortunately because i'm scaling the x and y axis independently, the ratio gets skewed, and I need to fix that. It's also severely limited by the maximum range of rednet. I've been trying to come up with a message rebroadcasting system that would allow me to monitor from farther away, but i hit limitations with textutils.unserialize with nested tables and haven't gone back to re-think it.

I just wish i could change color values on the screen to reflect depth. It's disconcerting when the turtle on my display stops moving to ascend 64 blocks and there's no feedback about what it's doing.

Sorry for my english ..
I could not start "aware"
you may describe more detailed how to install it properly ..?
I tried to follow the instructions to install it, but I must have done something wrong because it does not start.
thanks in advance

I couldn't start it on my friends SMP server, i told him to install it and he installed it correctly, but for some reason it says the API doesn't exist.
And.. on SSP, I get a Rednet error:
rednet:322: attempt to call nil

the rednet error would likely be because i'm assuming it's a wireless mining turtle, there should really be a toggle for that.
are you using the os.loadapi function to initialize it?

Sorry for the slow replies, folks - still looking for a tekkit or CC server where computercraft isn't broken or severely limited to test on.

installation instructions updated/clarified

Today I finished a couple new programs that make use of this API.
biodesign
-allows you to, using the terminal, design any structure up to 18x46 (height unlimited)
- these are saved to a directory structure based on the design name
biobuild
- run from a turtle, automatically builds a structure designed in the application above

these will be posted soon, after some further testing (likely later tonight)

I settled down to post the new source code and make a couple demo videos last night and ended up retooling every single program.
Version 2.0 is imminent and should be easier to set up (no longer resides in a directory)

• Designer program is a bit more polished and will allow you to design and build any structure up to ~46x16xN, with the ability to copy/paste entire levels.
• Builder works with updated designer files. Uses aware to build any structure you can create inside designer autonomously. Though you may have to manually refill if you use too many of the same inventory slot.
• Listener now attempts to roughly scale display feedback from miner so it's not stretched on a non-square display
• 2 new 'api' libraries required for some of the applications: utils and matrix, these will also be posted here
• utils includes the ability to download a text file off the internet if http api is installed, making installing/updating all of these files easier

As promised, the majority of 2.0 is now posted.
Feedback please :-)
biomine and biolisten are coming, but i'm tired and the video prep for biomine is going to be a bit of a pain.

No way biomine and biolisten are going up tonight - going to be working into the night at the office. And i have tickets to the Black Keys tomorrow :-)
look forward to it this weekend.

anyone making use of this?

I need suggestions/feedback for features etc for the next version.
I've already changed how all the files are saved to use a more centralized prefs-file style format that saves and reads n key/value pairs to file. In the next version all aware locations are stored in 1 file, and each design is its own file rather than a directory containing separate layer files.
With this approach, a design can (and will, if there's interest) support an inventory section that defines what blocks go in which slot, allowing for more than 63 of a block type before needing a refill - this would be part of the design program. I'd also like to add views that would allow a front to back, or side to side view rather than just top-down.
Perhaps also the ability to generate standard shapes (rectangle, hollow/filled, size n at x location)

I've also been testing the download function to allow any of the programs to be downloaded from the internet provided the http api is enabled, this works well :-).

Likely won't fuss with any of these things more if people aren't interested.

Man, you have really upped the ante. Basically, you did a lot of the stuff I was working on, so now I have to make something even harder.

Hmm… fully networked turtle swarms with proper spacial awareness doing all of the above tasks seems like a good new target point. Let the games begin!

(I mean, I could just use your APIs and stuff, but I think part of the problem with computercraft is that 95% of the fun is writing the code).

true enough :-)
most of what I've done so far is geared towards single turtles, for sure - mostly because of a lack of collusion avoidance.
All the solutions i came up with in the past would require the entire turtle work on some sort of action queue allowing it to listen for rednet signals and keep a running list of other turtle positions - but that won't work for non-wireless turtles and that annoys me. Plus, it would have to somehow negotiate what is a turtle that was broken at X location, and what turtles are simply idle - lots of things i don't really want to deal with for my own purposes.

I did get a pretty awesome idea yesterday that solves all of that – in theory – passively.
But i haven't yet started in on it or tested the mechanics really.
Also need to figure out conflict negotiation using logic rather than communication, because i don't want to have to rely on rednet at all.

Here is some feedback I have on your code. Keep in mind this is the nicest, most elegant set of APIs I have seen on here in a while, and I am really straining myself in order to provide you with some feedback. :P/>/>

Aware: I really like how you structured most of your functions. The modposition wrapper is very elegant, and the moveto() is a great solution for general movement. I don't understand why you have move in front of most of your functions… it makes them more verbose, and makes it harder to make Aware a drop-in replacement for the default turtle api (eg find all "turtle" and replace with "aware" in a file). Also, I really like the idea of the "shaft" flag, but I feel it could be done a tad better. Instead of a flag, give the turtle 3 modes: move, dig, and shaft. In move mode, it just tries to move. In dig mode, it digs in the direction it is trying to move, and once done, moves in that direction. In shaft mode, it does the same thing as dig mode, it also digs above itself. This would eliminate the need for the digging functions, and would make it simple to reuse code for each scenario, and would remove the bug where it digs forward into squares that in does not plan to move into when in shaft mode.

Biodesign and biobuild are amazing. Pure and simple. The way it only moves to blocks that actually need to be built is a neat optimization. In some cases, I imagine it would be nice if you could clear the are you are building in, or start at a different location. For example, a building with a basement. You could tell the turtle to build something, and WHERE it should start. The turtle goes to that location (digging down if it needs to) and then just goes through the entire area (possibly as a toggleable flag) clearing all the existing blocks and adding its own. As for the size limitation, instead of biobuild being artificially limited to 20*50, you should make it able to build any size, even manually created designs, as long as they follow the right basic structure. This has one major difficulty: you would have to store the ranges of x and y in your matrix for each layer, so it can be arbitrarily large. Ill get to this in a second. A feature request for buibuild would be to make it possible to "scroll" around, and make layers up to hundreds of squares in size, and possibly paste around objects within a layer to other coordinates, but that is a LOT of work. As an alternative: a simple tool that converts a layer expressed as a plaintext file into a layer, so you can manually design things using text editors.

Feature ideas: take a design, and split it into parts, send the parts to multiple turtles, and have them each do one part. Now you can make giganting floating castles in the sky in no time at all!

About the matrix program… I feel like yours does not add quite enough features over just doing it manually (array[x..":"..y]=3 seems just as easy as matrix.set(array, x, y), but that might just be me). I have decided to hack up a fully compatible, more universally useful version, which allows any number of dimentions. I'll post it as soon as I am done.

Good work!

Biopsy, on 22 May 2012 - 01:57 AM said:

All the solutions i came up with in the past would require the entire turtle work on some sort of action queue allowing it to listen for rednet signals and keep a running list of other turtle positions - but that won't work for non-wireless turtles and that annoys me.

Action queue is the same solution I came to. I wrote my existing code (that does similar things to your aware api, plus minimal pathfinding), then realized I wanted to make it work with swarms, so I am basically starting over and planning to do exactly that. It is difficult for sure, but it seems like the ultimate possible goal, so hey, why not.

I dont exactly understand your avoidance of rednet… it seems fine to me. Also, correct me if I am wrong, but couldn't turtles use the wired rednet api to communicate when in contact? It might be a little slow though…

kazagistar, on 22 May 2012 - 02:07 AM said:

Here is some feedback I have on your code. Keep in mind this is the nicest, most elegant set of APIs I have seen on here in a while, and I am really straining myself in order to provide you with some feedback. :P/>/>

Aware: I really like how you structured most of your functions. The modposition wrapper is very elegant, and the moveto() is a great solution for general movement. I don't understand why you have move in front of most of your functions… it makes them more verbose, and makes it harder to make Aware a drop-in replacement for the default turtle api (eg find all "turtle" and replace with "aware" in a file). Also, I really like the idea of the "shaft" flag, but I feel it could be done a tad better. Instead of a flag, give the turtle 3 modes: move, dig, and shaft. In move mode, it just tries to move. In dig mode, it digs in the direction it is trying to move, and once done, moves in that direction. In shaft mode, it does the same thing as dig mode, it also digs above itself. This would eliminate the need for the digging functions, and would make it simple to reuse code for each scenario, and would remove the bug where it digs forward into squares that in does not plan to move into when in shaft mode.

Biodesign and biobuild are amazing. Pure and simple. The way it only moves to blocks that actually need to be built is a neat optimization. In some cases, I imagine it would be nice if you could clear the are you are building in, or start at a different location. For example, a building with a basement. You could tell the turtle to build something, and WHERE it should start. The turtle goes to that location (digging down if it needs to) and then just goes through the entire area (possibly as a toggleable flag) clearing all the existing blocks and adding its own. As for the size limitation, instead of biobuild being artificially limited to 20*50, you should make it able to build any size, even manually created designs, as long as they follow the right basic structure. This has one major difficulty: you would have to store the ranges of x and y in your matrix for each layer, so it can be arbitrarily large. Ill get to this in a second. A feature request for buibuild would be to make it possible to "scroll" around, and make layers up to hundreds of squares in size, and possibly paste around objects within a layer to other coordinates, but that is a LOT of work. As an alternative: a simple tool that converts a layer expressed as a plaintext file into a layer, so you can manually design things using text editors.

Feature ideas: take a design, and split it into parts, send the parts to multiple turtles, and have them each do one part. Now you can make giganting floating castles in the sky in no time at all!

About the matrix program… I feel like yours does not add quite enough features over just doing it manually (array[x..":"..y]=3 seems just as easy as matrix.set(array, x, y), but that might just be me). I have decided to hack up a fully compatible, more universally useful version, which allows any number of dimentions. I'll post it as soon as I am done.

Good work!

Thanks for all the feedback! Glad to see someone's looking :-)
The verbosity was done on purpose early on so that i wouldn't accidentally confuse my own moves with turtle.'s, then when i added more later it got.. well.. verbose. The shaftmode was an afterthought to the mining app that i haven't posted yet. The extra blocks in front weren't an accident, it's supposed to dig 2-tall so i can walk, and 2-wide so i can have a ladder down to mining level, 1 block adjacent to the starting position.

The movement functions in general i'd like to clean up as those are some of the first lua functions I ever did, but haven't touched them because they just work (though i did go back and do the modposition thing when i changed how location was stored). I'll revisit them when i'm feeling masochistic :-)

Biobuild actually does build relative to itself, but the program itself doesn't determine movement. You could accomplish this by just using the little goto app and say "goto x y z o" then "build shack" - not quite as automatic as you're suggesting but i guess i could add in some command line arguments to automagically call goto? I'll have to think about the clearing flag - that shouldn't be too hard, but i'm not positive about that.

The copy/paste is doable, and i think i know how it will work.
The scrolling itself should be possible, but i'm not so sure about storing and traversing the data once the size is no longer known. I kinda cheated on that and now it's going to bite me.

That being said, I'm really not happy with the matrix format and i want to nix it altogether, ideally. The problem is multidimensional array init in lua - i haven't really figured out how to tackle that yet since they're really just nested tables, but you have to initialize a table before you can index it.
array = {}
array = {}
array[j] = 3
is very verbose, but you can't shortcut as far as i can tell. And I can't try to index uninitialized tables, so unless I give some arbitrary size limit to the layer size and just initialize a big empty nested 2d array to then come back and write values into, i'm not sure how to tackle it. I wrote matrix because i was bashing my head against 'attempt to index nil' errors when trying to manipulate layer tables.
I could avoid these problems for the time being if i limited structures to… say… 64x64xN - big enough?

I suppose turtles could work in tandem if they split up x/y areas instead of truly working in tandem. A program to parse and split a design file might accomplish this, i'll think on that.

kazagistar, on 22 May 2012 - 02:15 AM said:

Biopsy, on 22 May 2012 - 01:57 AM said:

All the solutions i came up with in the past would require the entire turtle work on some sort of action queue allowing it to listen for rednet signals and keep a running list of other turtle positions - but that won't work for non-wireless turtles and that annoys me.

Action queue is the same solution I came to. I wrote my existing code (that does similar things to your aware api, plus minimal pathfinding), then realized I wanted to make it work with swarms, so I am basically starting over and planning to do exactly that. It is difficult for sure, but it seems like the ultimate possible goal, so hey, why not.

I dont exactly understand your avoidance of rednet… it seems fine to me. Also, correct me if I am wrong, but couldn't turtles use the wired rednet api to communicate when in contact? It might be a little slow though…

The fact that turtles aren't multithreaded is what gets me. I don't really want to write an application the way i would need to in order to accomplish that. EVERY program would have to submit to some sort of queue, and that's just no fun in my opinion.

My latest idea, however, is when i do my detect() before movement and it comes back true, i can check to see if a peripheral exists in that block, and if so - attempt to get it's computer ID. Then do something where if my ID is less than theirs, i have seniority. Then the one with the higher ID sends a redstone signal to indicate they're moving out of the way, move, then the older one resumes. If the older one doesn't get a redstone signal in some time frame, they assume it's inactive or a computer and attempt to move around it.
That would work on all turtles regardless of wireless status. But i haven't tested to make sure there won't be a race condition where they go all thunderdome on each other =)

Whenever I try to use one of the aware move functions, I get "aware:14: attempt to call nil". Maybe because reportpositions() is local?

Also, when I do aware.getposition() it just returns something like table:1b8dc93f.

D3matt, on 24 May 2012 - 07:05 PM said:

Whenever I try to use one of the aware move functions, I get "aware:14: attempt to call nil". Maybe because reportpositions() is local?

Also, when I do aware.getposition() it just returns something like table:1b8dc93f.

getposition will return a table of format {x,y,z,orientation} so that is expected, the attempt to call nil is a bit harder - did you call os.loadAPI("<path-to-aware>") before attempting to call? The local (if it was local in 2.0) shouldn't matter as it's being called within its own scope, so the likely culprit is that the position either hasn't been initialized (which should happen when the API is loaded) or the API isn't loaded at all. It also may happen if the required utils library isn't present - that'll break it.



Just got back from a vacation, new stuff will be coming when i get back into the routine.

Finally a use for those damn turtles!

Biopsy, on 29 May 2012 - 02:08 AM said:

D3matt, on 24 May 2012 - 07:05 PM said:

Whenever I try to use one of the aware move functions, I get "aware:14: attempt to call nil". Maybe because reportpositions() is local?

Also, when I do aware.getposition() it just returns something like table:1b8dc93f.

getposition will return a table of format {x,y,z,orientation} so that is expected, the attempt to call nil is a bit harder - did you call os.loadAPI("<path-to-aware>") before attempting to call? The local (if it was local in 2.0) shouldn't matter as it's being called within its own scope, so the likely culprit is that the position either hasn't been initialized (which should happen when the API is loaded) or the API isn't loaded at all. It also may happen if the required utils library isn't present - that'll break it.



Just got back from a vacation, new stuff will be coming when i get back into the routine.

I loaded both Utils and Aware, yes. I got the turtle to move even though it was throwing the nil errors, but it wouldn't turn. I was running from the LUA command prompt if that makes a difference.

Hi! im trying to use your aware api but i always get an error when i put it at the apis folder or try to load it with lua os.loadAPI() , i already have the utils api and loaded.
The error i always get (and my friends get it too) is this one:

file not found
aware:243: attempt to index  ? (a nil  

i've tried to put the api in apis/turtle, then i get the next error:

file not found
rednet:322: attemp to call nil  

can u help me to get this working?

fyi, i'm trying this on a minecraft fresh install, only with computercraft mod, and the default apis

a small request, or question. is there a way to make the commands just be dump() instead of aware.dump()? it would make it easier for me to write big programs and have it do certain functions faster, and easier for me to remember what each does. otherwise great API, really helpful for returning my turtle to base when its been making tunnels for me.

I hope the author is still around! =) I'm in love with the idea of the biodesign &amp; build programs but I can't get the biobuilder to work. (aware:14: attempt to call nil, EDIT: the turtle moves ahead one block before returning this error) Is this program suite compatible with CC 1.53/MC 1.5.2? Am I being a total noob and forgot a vital part?

I am currently on an FTB Unleashed SMP server,
using a Wireless Turtle,
utils 2.0, matrix 2.0, aware 2.0, biodesign 2.0 and biobuild 2.0 installed.

Regards,
Andruvan

Pesoen, on 05 November 2013 - 05:42 PM said:

a small request, or question. is there a way to make the commands just be dump() instead of aware.dump()? it would make it easier for me to write big programs and have it do certain functions faster, and easier for me to remember what each does. otherwise great API, really helpful for returning my turtle to base when its been making tunnels for me.

If I remember correctly (I'm a little rusty with LUA :P/>)
You should be able to put this at the top of your program…

local dump = aware.dump

And then you should just be able to use dump().

Do something with those adf.ly URLs… I don't think you're allowed to use them on this forum.

GPS:238: couldn't determin orientation

is this API still active? i would love to be able to use it but i am always encountering errors.