Quick Start 

Welcome to Lift! The fastest way to get started building your algorithm is to take an SDK and use it as a base for your code.

SDKs and Libraries 

• https://github.com/kingsawyer/python_lift_api

 

 

 

Further Reading 

If you're interested in building a client from the ground up, you'll need to have a websocket client to connect to the Lift server. A decent Chrone extension is Simple Websocket Client. When you connect, you can start a building by choosing a , entering a username of up to 20 alphanumeric characters, email address, and optionally event information. Your email address will never be sold or shared.

Open a connection

Open a connection to:

ws://codelift.org/v2/building

You will receive a response that looks something like this:

{"status":"connected","message":"Connected"}

Start a building

Start a new building by sending:

{"username":"[YOUR_USERNAME]", "email":"[YOUR_EMAIL_ADDRESS]", "plan":"training_1",
"event_name":"[OPTIONAL_EVENT_NAME]", "event_id":"[OPTIONAL_EVENT_ID]"}

Now is where it gets interesting! The response will be an entire building elevator system state!

{
	"floors": 10,
	"elevators": [
		{
			"id": 0,
			"floor": 0,
			"buttons_pressed": []
		},
		{
			"id": 1,
			"floor": 4,
			"buttons_pressed": []
		}
	],
	"requests": [],
	"status": "in_progress",
	"message": "Building In Progress"
}

Control Elevators

Let's issue a command now. Try the following:

{"commands":{"0":{"speed":1,"direction":1}}}

In the system response you should see that elevator "0" has now moved up to floor "1". You'll also notice something interesting in the "requests" object. Someone's requesting an elevator!

"requests": [
	{
		"direction": -1,
		"floor": 3
	}
],

You'll need to control an elevator to respond to this request, and the request will only be fulfilled if you stop an elevator on that floor, but set the direction to be the same as the request, for an entire request cycle. At this point it's probably beyond the scope of using Simple Websocket Client, though, so it's time to start building your control system! Take a look at the Building Rules to get an idea about how Buildings work and the API Reference for more detailed information.

Building Rules 

• The system interface is of a common basic elevator. Each floor has either one or two buttons labeled "up" or "down". Each elevator has an external light indicating it's direction. Inside each elevator is a control panel with buttons for every floor in the building.
• All floors are accessible by all elevators.
• A building has a ground floor (floor 0) in addition to the number of floors listed.
• You will always receive a full state of the building, including the state of all elevators and the current set of requests.
• Each request cycle, or "turn", the following happens:
  • Any elevator with a non-zero speed will move according to it's direction.
  • Any elevator with a speed of zero will open it's doors, clear the button press for the current floor, and allow passengers to board.
  • Elevators will not go outside the bounds of the building.
• Multiple elevator floor requests may occur in a single turn. Ordering of elevator floor requests requests is not guaranteed to be consistent from turn to turn.
• A passenger will only board an elevator if it is on the same floor, pointed in the same direction, and stopped for a full turn.
• Passengers will only leave an elevator if it is stopped on their destination floor for a full turn.
• When a passenger boards an elevator, they will press a button in that elevator, which may or may not add to the list of buttons pressed. It is not possible to know what the destination for an individual passenger is.
• If a passenger has multiple options for elevators to board, they will choose at random.
• New passenger requests may be added to the building until the building is complete.

Building Plans 

Building Plans are essentially a blueprint for your building. They describe how many floors and elevators exist, and contain all possible passenger requests for the entire lifetime of the building. Every time you build a building from the same plan id, you will get the exact same experience. This allows for consistent scoring on a plan-by-plan basis. See the full list of plans.

Scoring 

There are four metrics that compose a building's score. Different buildings may care more about one metric vs another.

• Wait Score - How much time passengers had to wait before boarding an elevator
• Trip Score - Based on the time passengers spend in an elevator
• Energy Score - A measure of the energy effienciency of the building
• Maintenance Score - Tracks the distribution of load amongst elevators

Only complete buildings will be eligible for leaderboards.

API Reference 

Endpoint: ws://codelift.org/v2/building

Building Creation

Request

{
	"username":"silvamerica",  # {String} Required, alphanumeric length <= 20
	"email":"name@domain.com", # {String} Required, valid email address
	"plan":"training_1",       # {String} Required, must exist in plans
	"event_name":"pycon2015",  # {String} Optional, must be active in events
	"event_id":"123abc",       # {String} Optional, valid event identifier,
							   # such as your registration number
}

Response

{
	"floors": 10,                 # {Integer} Required
	"elevators": [                # {Array} Required, array of objects
		{
			"id": 0,              # {Integer} Required
			"floor": 4,           # {Integer} Required
			"buttons_pressed": [] # {Array} Required, array of Integers or []
		}...
	],
	"requests": [                 # {Array} Required, array of objects or []
		{
			"direction": -1,      # {Integer} Required
			"floor": 3            # {Integer} Required
		}...
	],
	"status": "in_progress",      # {String} Required, "in_progress"
	"message": "Building In ...", # {String} Required, either message or ""
}

Building Simulation

Request

{
	"commands": {            # {Object} Required, if no commands, use {}
		"0": {               # {Key} Required, elevator id
			"direction": -1, # {Integer} Optional, values other than -1 or 1 ignored
			"speed": 1       # {Integer} Optional, values other than 0 or 1 ignored
		}...
	}
}

Response

Same as Building Creation response above

Building Finished

Response

{
	"status": "finished",         # {String} Required, "finished"
	"message": "Building Fi ...", # {String} Required, either message or ""
	"visualization": "http://...",# {String} Required, url to visualize your building
	"score": 6122,                # {String} Required
	"event_code": "61ABF2"        # {String} Optional, present at the end of a
								  # simulation for buildings eligible for a prize
								  # (while supplies last)
}